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1. Introduction 


1.1 Purpose 


In this document we introduce the Lisp programming environment of the Symbolics Lisp 
Machine. Using a single example program, we present one style of interacting with that 
environment in developing Lisp programs. We do not prescribe a "best" style of programming 
on the Lisp Machine. Rather, we suggest some techniques and combinations of features that 
expert Lisp Machine programmers advocate. You might find these techniques useful in 
developing a comfortable and efficient Lisp Machine programming style of your own. 


1.2 Prerequisites 


This document is for you if you will be writing or maintaining Lisp programs and have recently 
begun to use a Lisp Machine. The document will be most useful if you have some experience 
writing Lisp programs and are familiar with basic features of the Lisp Machine. The document 
is not a survey of Lisp Machine facilities, a reference manual, or a Lisp primer. You might 
find the following Symbolics publications helpful when reading this document: 


e Lisp Machine Summary 

e Program Development Help Facilities 
e Lisp Machine Manual 

e An up-to-date set of release notes 


1.3 Scope 


We focus in this document on interaction between programmers and the Lisp Machine. We 
present some ways of using Lisp Machine features that you might find helpful at each stage of 
program development. We mention some broad issues of style in designing programs, including 
modularity and efficiency, but we do not explore program structure in any depth. We do not 
discuss matters of style in using Lisp, such as appropriate uses for structures and flavors. 


This document corresponds to the Symbolics 3600. Some key bindings and symbol names are 
different on the Symbolics LM-2. 


1.4 Method 


We derived the methods we describe here by working with Lisp Machine programmers at 
Symbolics. Some of these programmers were early developers of the machine itself. Their —__ 
styles vary. Like most programmers, they generally do not follow a simple textbook sequence 
of designing, coding, compiling, debugging, recompiling, testing, and debugging again. Instead, 
they develop programs in repeated cycles, each a sequence of editing, compiling, testing, and 
debugging. These cycles are often nested. For example, an error in testing a program invokes 
the Debugger; from the Debugger the programmer types Lisp forms or calls the editor to 
change and recompile code; an error in retesting code from the Debugger invokes the Debugger 
again. 
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1.5 Features 


Symbolics developers have designed the Lisp Machine to accommodate a relatively spontaneous 
and incremental programming style. Five Lisp Machine features make up an integrated 
programming environment. 


e The Zetalisp environment. The Lisp system code allows you to write 
programs that are extensions of the environment itself. You can often 
produce complex programs with comparatively little new code. Zetalisp 
flavors \et you build data structures with complex modular combinations of 
associated procedures and state information. 


The window system. Windows permit you to shift rapidly among such 
activities as editing, evaluating Lisp, and debugging. You can suspend an 
activity in one window, switch to another, and return to the first without 
losing its state. You can display several activities on the same screen. 
Because the window system is itself implemented with Zetalisp flavors, you 
can modify or create windows for special displays. 


The Zmacs text editor. Zmacs has sophisticated means of keeping track of 
Lisp syntax. It interacts with the Zetalisp environment, letting you find out 
about existing code and incorporate it into your programs. Unlike some 
structure editors, Zmacs allows you to leave definitions incomplete until you 
are ready to evaluate or compile them. 


Dynamic compiling, linking, and loading. The compiler is always loaded. 

You can use single-keystroke commands to compile and load source code 
from a Zmacs buffer. You can write, compile, test, edit, and recompile code 
in sections. When you recompile a function definition, the function’s callers 
use the new definition. 


Interactive debugging. Errors invoke the Debugger in their dynamic 
environments. From the Debugger you can examine the stack, change 
values of variables and arguments, call the editor to change and recompile 
source code, and reinvoke functions. 


1.6 Organization 


The sequence of steps in developing a program on the Lisp Machine is too complex to mirror 
in the linear organization of a document. We emphasize the cyclical course of program 
development, but we have organized he document in a simple way. We present the main 
programming sequence in the next three chapters. These deal simply with writing and editing, 
evaluating and compiling, and debugging code. We discuss particular Zetalisp functions, Zmacs 
commands, and other features where they appear most useful or where they present alternatives 
to common techniques. 


The next. three chapters require virtually no knowledge of flavors or the window system. But 
knowing about flavors and windows is essential to advanced use of the Symbolics Lisp Machine. 
Chapter 5 presents some simple uses of flavors and windows and some programming aids for 
working with them. 


Throughout, we use as an example the development of a single program that draws the 
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recursive arrows in the cover design for this document. Sandy Schafer and Bernard LaCasse of 
Schafer /LaCasse created the original design. Richard Bryan of Symbolics wrote and we revised 
a Lisp program that simulates it. The complete code appears in appendixes A (page 133) 

and B (page 147) and in the files SYS: EXAMPLES; ARROW-CALC LISP and 

SYS: EXAMPLES; ARROW-OUT LISP. (To run the program, load 

SYS: EXAMPLES; ARROW.) A reproduction of the design produced on a Symbolics LGP-1 
Laser Graphics Printer appears in appendix C (page 165). 


Many of the techniques and facilities we mention are helpful at more than one stage of 
program development. Conversely, the Lisp Machine provides many paths for accomplishing 
tasks at each stage. As programmers at Symbolics gladly acknowledge, there is more than one 
way to do almost anything on the Lisp Machine. 


1.7 Notation Conventions 


Modifier keys are designed to be held down while pressing other keys. They do not themselves 
transmit characters. A combined keystroke like META-X is pronounced "meta x" and written as 
m-X. This notation means press the META key and, while holding it down, press the X key. 


Modifier keys are abbreviated as follows: 


Key Abbreviation 
CTRL Cc 

META m- 

SUPER s~ 

HYPER h- 

SHIFT sh- 


The keys with white lettering (like X or SELECT) all transmit characters. Combinations of 
these keys are meant to be pressed in sequence. This sequence is written as, for example, 
SELECT L. This notation means press the SELECT key, release it, and then press the L key. 


This document uses the following notation conventions: 


Appearance in document Representing 

send, chaos:host-up Printed representation of Lisp objects in running text. 

RETURN, ABORT, c-F Keyboard keys. 

SPACE Space bar. 

login Literal type-in. 

(make-symbol "foo") Lisp code examples. 

(function-name arg/ arg2) Syntax description of the invocation of function-name. 

argl Argument to the function function-name, usually expressed as a 
word that reflects the type of argument (e.g., string). 

grg2 Optional argument; you can leave it out. 

Undo, Tree Edit Any Command names in Zmacs and Zmail appear with initial letter of 
each word capitalized. 

Insert File (m-%) Extended command names in Zmacs and Zmail. Use m-X to 
invoke one. 

[Map Over] Menu items. : 

(L), (R2) Mouse clicks: L=left, L2=double click left, M=middle, 


M2=double click middle, R=right, R2=double click right. 
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Mouse commands use notations for menu items and mouse clicks in the following ways: 


1. Square brackets delimit a mouse command. 
2. Slashes (/) separate the members of a compound mouse command. 
3. The standard clicking pattern is as follows: 


e For a single menu item, always click left. For example, the following two 
commands are exactly the same: 


[Previous] 
[Previous (L)] 


e For a compound command, always click right on each menu item except the 
last, where you click left. For example, the following two compound 
commands are exactly the same: 


[Map Over / Move / Hardcopy] 
[Map Over (R) / Move (R) / Hardcopy (L)] 


4. When the notation does not follow the standard, it shows explicitly which 
button to click. For example: ; 


[Map Over / Move (M)] 
[Previous (R)] 


In the sections of this document that develop the Lisp code for the example program, we use 
change bars to distinguish new or changed code from code that we have already presented. 
Whenever we display a line of code that has not appeared before, and whenever we change a 
line of code that has already appeared, we place a vertical bar (|) next to that line in the left 
margin. This bar is not part of the code itself. In the following example, we change two lines 
of the definition of draw-big-arrow: 


(defun draw-big-arrow () 
3; Determine coordinates of arrowhead vertexes 
(multiple-value-bind 
(*plx* Sply® *p2x® *p2y*® *p5x* *p5y*® *p6x*? *p6y*) 
(compute-arrowhead-points) 
3; Determine coordinates of shaft vertexes 
(multiple-value-bind (*p3x* *p3y* *p4x® *p4y*®) 
(compute-arrow-shaft-points) 
(draw-big-outline) ;Outline arrow 
(when *do-the-stripes® é 
(str ipe-arrowhead))))) ;Stripe head 


Program Development Tools and Techniques > 


Symbolics, Inc. 


2. Writing and Editing Code 


Symbolics Lisp Machine programmers seldom write programs in sequence, from beginning to 
end, before testing them. They often leave definitions incomplete, skip to other definitions, and 
then return to finish the incomplete forms. They search for existing code to incorporate into 
new programs. They edit their work frequently, changing code while writing, testing, and 
maintaining programs. 


In this chapter we discuss Lisp Machine features, particularly Zmacs commands and Zetalisp 
functions, that make this style natural. Many of these features are useful at other stages of 
programming as well: Editing techniques are important in program maintenance, and methods 
of learning about existing code are helpful in debugging. 


To illustrate programming methods, we develop a program that draws the recursive arrow 
design that appears on the cover of this document. (The program does not draw the horizontal 
stripes outside the large arrow.) We produce the figure on a Symbolics LGP-1 Laser Graphics 
Printer, a Lisp Machine screen, or a file. We develop-the program in four stages, beginning 
with simple procedures to outline the arrows and progressively modifying the code to refine the 
figure: 


1. Drawing the borders of the large arrow and of the smaller recursively 
drawn arrows that it encloses 


2. Drawing the diagonal stripes within the figure, but with uniform thickness 
and spacing 


3. Changing the stripes to vary in thickness and spacing 
4. Writing the routines that control the output destination 


Appendixes A (page 133), B (page 147), and C (page 165) contain the code for the sample 
program and a reproduction of the LGP image the program produces. 


2.1 Before You Begin 


Use the Zmacs text editor to write and edit programs. Zmacs has many features that provide 
information about Zmacs commands, existing code, buffers, and files. Two features are 
generally useful: the HELP key and completion. (See Program Development Help Facilities for 
details.) . 


2.1.1 HELP 
Pressing the HELP key in a Zmacs editing window gives information about 
Zmacs commands and variables. The kind of information it displays 
depends on the key you press after HELP. 


Reference 
HELP ? Displays a summary of HELP options. 
HELP A Displays names, key bindings, and brief descriptions of 


commands whose names contain a string you specify. 
(A refers to "apropos".) . 
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HELP C Displays the name and brief description of a command 
bound to a key you specify. 

HELP D Displays long documentation for a command you specify. 

HELP L. Displays a listing of the last 60 keys you pressed. 

HELP U Offers to "undo" the last major Zmacs operation, such as 
sorting or filling, when possible. 

HELP V Displays the names and values of Zmacs variables whose 
names contain a string you specify. 

HELP W Displays the key binding for a command you specify. 
(W refers to "where".) 

HELP SPACE Repeats the last HELP command. 


2.1.2 Completion 
Some Zmacs operations require you to provide names — for example, names 
of extended commands, Lisp objects, buffers, or files. You usually supply 
names by typing characters into a minibuffer that appears near the bottom 
of the screen. Often you do not have to type all the characters of a name; 
Zmacs offers completion over some name spaces. When completion is 
available, the word "Completion" appears in parentheses above the right side 
of the minibuffer. 


You can request completion when you have typed enough characters to 
specify a unique word or name. For extended commands and most other 
names, completion works on initial substrings of each word. For example, 
m-X c b is sufficient to specify the extended command Compile Buffer. 
SPACE, COMPLETE, RETURN, and END complete names in different ways. 
HELP and [Zmacs Window (R)] list possible completions for the characters 
you have typed. 


Reference 

SPACE Completes words up to the current 
word. 

HELP or c-? Displays possible completions in the 
typeout area. 

{Zmacs Window (R)] Pops up a menu of possible 
completions. 

COMPLETE Displays the full name if possible. 

RETURN or END Confirms the name if possible, 


whether or not you have seen the full 
name. 


N 
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2.2 Getting Started 
When Symbolics programmers begin to write new Lisp programs, they often follow these steps: 
1. Enter the Zmacs editor. 


2. Create a buffer for a new file for the program. 
3. Set the attributes of the buffer and file, including major and minor modes. 


2.2.1 Entering Zmacs 
Use SELECT E or [Edit] from a system menu to enter Zmacs. 


Reference 
SELECT E Selects a Zmacs frame. 
{Edit] (from a system menu) Selects a Zmacs frame. 


2.2.2 Creating a File 
To store program code in a new file, use Find File (e-X ¢-F) to create a 
buffer for the file at the beginning of the editing session. You can then 
edit the file’s attributes or create an attribute list that appears in the text 
(see section 2.2.3, page 7). You will not have to interrupt later work to 
name the file or check its attributes before you save it. 


Reference . 

Find File (c-% c-F) Creates and names a buffer for the 
file, reading in the file if it already 
exists. 


2.2.3 File Attribute Lists 
Each buffer and generic pathname has attributes, such as Package and Base, 
which can also be displayed in the text of the buffer or file as an attribute 
list. An attribute list must be the first nonblank line of a file, and it must 
set off the listing of attributes on each side with the characters "-*-". If 
this line appears in a file, the attributes it specifies are bound to the values 
in the attribute list when you read or load the file. 


Suppose you want the new program to be part of a package named 
graphics that contains graphics programs. In this case, you want to set the 
Package attribute to graphics in three places: the generic pathname’s 
property list; the buffer data structure; and the buffer text. You can make 
the change in two ways: 


e If the package already exists in your Lisp environment, use Set Package 
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(m-X) to set the package for the buffer. The command asks you whether or 
not to set the package for the file and attribute list as well. You cannot 
use this command to create a new package. 

Use Update Attribute List (-X) to transfer the current buffer attributes to 
the file and create a text attribute list. Edit the attribute list, changing the 
package. Use Reparse Attribute List (m-X) to transfer the attributes in the 
attribute list to the file and the buffer data structure. If the package you 
specify by editing the attribute list does not exist in your Lisp environment, 
Reparse Attribute List asks you whether or not to create it under global. 


When you specify a package by editing the attribute list, you can explicitly 
name the package’s superpackage and, if you want, give an initial estimate 
of the number of symbols in the package. (If the number of symbols 
exceeds this estimate, the name space expands automatically.) Instead of 
typing the name of the package, type a representation of a list of the form 
(package superpackage symbol-count). To indicate that the graphics 


_ package is inferior to global and might contain 1,000 symbols, type into the 


attribute list: 


Package: (GRAPHICS GLOBAL 1000) 


See the Lisp Machine Manual, section 21.9.2, page 369, and Release 4.0 
Release Notes, sections 5.3.5 and 5.3.6, page 90, for more on file and buffer 
attributes. 


Example 

Suppose the package for the current buffer is user and the base is 8. We 
want to create a package called graphics for the buffer and associated file. 
We also want to set the base to 10. If no attribute list exists, we use 
Update Attribute List (m-X) to create one using the attributes of the 
current buffer. An attribute list appears as the first line of the buffer: 


333 -*- Mode: LISP; Package: USER; Base: 8 -*- 


Now we edit the buffer attribute list to change the package specification 
from USER to (GRAPHICS GLOBAL 1000) and to change the base specification 
from 8 to 10. The text attribute list now appears as follows: 


333 -®- Mode: LISP; Package: (GRAPHICS GLOBAL 1000); Base: 10 -*- 


Finally, we use Reparse Attribute List (m-X). The package becomes 
graphics and the base 10 for the buffer and the file. 
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Reference 

Set attribute (m-%) Sets attribute for the current buffer. 
Queries whether or not to set 
attribute for the file and in the text 
attribute list. attribute is one of the 
following: Backspace, Base, Fonts, 
Lowercase, Nofill, Package, Patch 
File, Tab Width, or Vsp. 


Update Attribute List (m-%) Assigns attributes of the current 
buffer to the associated file and the 
text attribute list. 


Reparse Attribute List (m-X) Transfers attributes from the text 
attribute list to the buffer data 
structure and the associated file. 


2.2.4 Major and Minor Modes 


Each Zmacs buffer has a major mode that determines how Zmacs parses the 
buffer and how some commands operate. Lisp Mode is best suited to 
writing and editing Lisp code. In this major mode, Zmacs parses buffers so 
that commands to find, compile, and evaluate Lisp code can operate on 
definitions and other Lisp expressions. Other Zmacs commands, including 
LINE, TAB, and comment handlers, treat text according to Lisp syntax rules 
(see section 2.4, page 19). 


If you name a file with one of the types associated with the canonical type | 
:lisp, its buffer automatically enters Lisp Mode. Following are some 
examples of names of files of canonical type :lisp: 


Host system File name 

Lisp Machine acme-blue: >symbol ics>examp les>arrow. lisp 
TOPS-20 acme-20:<symbolics.examples>arrow. lisp 
UNIX acme-vax: /symbolics/examples/arrow. 1 


You can also specify minor modes, including Electric Shift Lock Mode and 
Atom Word Mode, that affect alphabetic case and cursor movement. 
Whether or not you use these modes is a matter of personal preference. If 
you want Lisp Mode to include these minor modes by default, you can set a 
special variable in an init file. If you want to exit one of these modes, 
simply repeat the extended command. The command acts as a toggle switch 
for the mode. 
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Example 
The following code in an init file makes Lisp Mode include Electric Shift 
Lock Mode if the buffer’s Lowercase attribute is nil, as it is by default: 


(login-forms 
(setq zwei: 1isp-mode-hook 
*zwei:electric-shift-lock-if-appropriate) ) 


Reference 

Lisp Mode (m-X) Treats text as Lisp code in parsing 
buffers and executing some Zmacs 
commands. 

Electric Shift Lock Mode (m-%) Places all text except comments and 
strings in upper case. 

Atom Word Mode (m-%) Makes Zmacs word-manipulation 
commands (such as m-F) operate on 
Lisp symbol names. 

Auto Fill Mode (m-#) Automatically breaks lines that 
extend beyond a preset fill column. 

Set Fill Column (c-X F) Sets the fill column to be the column 


that represents the current cursor 
position. With a numeric argument 
less than 200, sets the fill column to 
that many characters. With a larger 
numeric argument, sets the fill 
column to that many pixels. 


2.3 Program Development: Design and Figure Outline 


2.3.1 Program Strategy 
Our goal in developing the sample program is to reproduce the pattern of 
striped arrows on the cover of this document. The pattern consists of one 
large arrow enclosing many small arrows that are similar to each other. 
Each arrow is a series of line segments that form either its outline or its 
stripes. 


We have two general problems in writing the program. We must calculate 
the position of each line segment we want to draw. We must also convert 
these positions into a form that will produce line segments on the output 
device we choose. 


In solving these problems, we want to adhere to two principles: 
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We want the program to be as modular as possible. The routines that 
calculate line positions should not depend on the output device we choose. 
The routines that translate positions for the output device should not 
depend on any particular method of calculating those positions. If we want 
to change the internal operation of either set of routines, we should not 
have to change the other. 

We want to write the program in an incremental style. We write the 
program in stages, producing a working version at each stage. We start 
with simple tasks and gradually add refinements until we are satisfied with 
what the program accomplishes. 


We write the program in two modules, one to calculate line positions and 
the other to translate positions for the output streams. We put these 
modules in separate files: The first appears in appendix A (page 133), the 
second in appendix B (page 147). 


How do we send line positions from the module that calculates them to the 
module that transmits them to output? The output module, which we 
discuss in detail in chapter 5 (page 101), consists of definitions of flavors 
and methods to transfer information to the appropriate output stream. 


' Streams for LGP and screen output can both produce lines using the 


coordinates of the endpoints. Our module that calculates line positions 
needs to compute the coordinates of the endpoints of the lines to be drawn. 
In the output module, we define a generic operation called :show-lines to 


-receive the coordinates from the calculation module and translate them for 


the appropriate output stream. The calculation module sends :show-lines 
messages to the output module. We can decide at run time which output 
stream to use. 


Now that we have defined the interface between the two modules, we could 
in principle write either module first. Although we want the position- 
calculating routines to be independent of the output device, we have to 
choose a coordinate system for the calculations. For ease of interpretation, 
we place the origin at bottom left. This is the convention that the system 
LGP routines use, but the origin for screen coordinates is at top left. For 
the sake of convenience, we calculate positions in units of LGP pixels. 


2.3.2 Simple Screen Output 


We discuss the output routines in chapter 5 (page 101). Eventually, we 
want to produce output on the screen, an LGP, or a file. To develop the 
program, we need a routine for simple screen display so that we can check 
the results of our calculation routines. We can use the stream that is the 
value of terminal-io. This stream handles :draw-line messages whose 
arguments include the coordinates of the endpoints of the lines to be drawn. 
(See Introduction to Using the Window System, section 2.4, page 30, for more 
on :draw-line.) 
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We first create a source file for the output routine. We define a flavor, 
screen-arrow-output, and a method to handle :show-lines messages from 
the calculation routines. The arguments to :show-lines are the coordinates 
of the endpoints of one or more lines to be drawn. If the message has more 
than four arguments — the coordinates of two endpoints —- we assume that 
we are to draw more than one line, each starting at the endpoint of the last. 
The :show-lines method must iterate over the arguments of the message 
and send terminal-io a :draw-line message for each line to be drawn. 


We must remember to transform the y-coordinate to take account of the 
screen’s origin at the top. We must also scale both coordinates to take 
account of the LGP’s higher resolution: Screen pixels are about 2.5 times as 
large as LGP pixels. 


The following code provides this simple output module: 


(defflavor screen-arrow-ocutput 
((scale-factor 2.5)) 


()) 


(defmethod (screen-arrow-output :show-lines) 
(x y &rest x-y-pairs) 

(loop for x0 = (send self *:compute-x x) then xl 
for yO = (send self °’:compute-y y) then yl 
for (xl yl) on x-y-pairs by #’cddr 
do (setq xl (send self °:compute-x x1) 

yl (send self *:compute-y yl)) 
(send terminal-io °:draw-line 
x0 yO xl yl tv:alu-ior t))) 


(defmethod (screen-arrow-output :compute-x) (x) 
(fixr (// x scale-factor))) 


(defmethod (screen-arrow-output :compute-y) (y) 
(fixr (- 800 (// y scale-factor)))) 


2.3.3 Outlining the Figure 


We now begin to write the module that calculates the coordinates of the 
lines that make up the figure. First we must decide how to represent the 
large arrow that encloses the figure and the smaller arrows inside it. As the 
diagram in appendix A (page 133) shows, seven points define each arrow. 
Each arrow has a head, bounded by points 0, 1, and 6, and a shaft, bounded 
by points 2, 3, 4, and 5. The large outer arrow and the smaller inner 
arrows differ in their shafts. Each inner arrow has two yet smaller arrows 
beneath it. The inferior arrows overlap the shafts of the superior arrows 
and turn each shaft into a series of descending triangles. 


We have two kinds of arrow, represented by the large outer arrow and the 
small inner ones. We can treat these differences in several ways: 
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e We can define two structures, make each arrow an instance of one of the 
structures, and store information about each arrow in the structure’s slots 
(see the Lisp Machine Manual, chapter 19, page 257). 


e We can define two flavors, make each arrow an instance of one of the 
flavors, and store information about each arrow in the flavor’s instance 
variables (see the Lisp Machine Manual, chapter 20, page 279). 


We can simply define global variables to represent the state of the current 
arrow. 


Whichever method we choose, some operations, such as striping the 
arrowheads, will be the same for both kinds of arrows. Other operations, 
such as striping the shafts, will depend on the kind of arrow we are 
drawing. 


For simplicity, we use global variables to hold information about the arrows, 
and we use functions to define procedures for calculating coordinates. Note 
that we bind the global variables rather than ser them. We do this because 
we might eventually have two or more arrow programs running at the same 
time in separate processes. If we set global variables, one program might 
incorrectly use a value set by another (see section 5.1.6, page 117). 


Our first task in writing the calculation module is to outline the arrows. 
After creating a file for the module, we write the code for this task in six 
steps: 


1. Define variables to hold information about the arrow we are drawing. For 


the :show-lines message we need the x- and y-coordinates of the seven 
points that define the arrow. We also need the length of the top edge of 
the arrow, which we use as a base length. In calculating coordinates, we 
also need the values of one-half and one-fourth the length of the top edge. 


We use defvar to declare global variables near the beginning of the file (see 
the Lisp Machine Manual, section 3.1, page 14). This macro declares 
variables special for the compiler and lets us supply default initial values and 
documentation strings. By convention, we surround the names of global 
variables with asterisks to distinguish them from names of local variables. 


(defvar *top-edge* nil 
“Length of the top edge of the arrow") 


(defvar *top-edge-2* nil 
"Half the length of the top edge") 


(defvar *top-edge-4* nil 
"One-fourth the length of the top edge") 


(defvar *p0x* nil 
“X-coordinate of point 0") 
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(defvar *p0y? nil 
"“Y-coordinate of 


(defvar *plx* nil 
'"X-coordinate of 


(defvar *ply* nil 
“Y¥-coordinate of 


(defvar *p2x* nil 
"X-coordinate of 


(defvar *p2y* nil 
“Y-coordinate of 


(defvar *p3x* nil 
"X-coordinate of 


(defvar *p3y* nil 
"Y-coordinate of 


(defvar *p4x® nil 
"X-coordinate of 


(defvar *p4y* nil 
"Y-coordinate of 


(defvar *p5x* nil 
"X-coordinate of 


(defvar *p5y*® nil 
"“Y-coordinate of 


(defvar *p6x* nil 
"X-coordinate of 


{defvar *p6y* nil 
"Y-coordinate of 
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. Define an initial function, draw-arrow-graphic, for the calculation module. 


We will call this function from the one we invoke to start the program. We 
pass draw-arrow-graphic the length of the top edge of the large arrow and 
the coordinates of its top right point (point 0). These arguments determine 
the position and size of the arrow. The function also calculates the half 
and quarter lengths of the top edge. 


(defun draw-arrow-graphic (*top-edge* *p0x*® *p0y*) 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top~edge* 4))))) 
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3. Outline the large arrow. We compute the coordinates of the other six 


points of the arrow, then send a :show-lines message to draw the lines. We 
can calculate the coordinates of points 1, 2, 5, and 6 the same way for both 
the large and smail arrows. We put these calculations in a separate function 
so that we can use the same code for both kinds of arrow. We need a 
constant to hold the destination of the :show-lines messages. We must add 
to draw-arrow-graphic a call to draw-big-arrow. 


(defconst *dest* nil 
“Destination of :SHOW-LINES messages to output") 


(defun draw-arrow-graphic (*top-edge* *p0x*® *p0y*) 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4))) 
(draw-big-arrow) )) 


(defun draw-big-arrow () 
(multiple-value-bind 
(*plx® *ply* *p2x® *p2y*® *p5x® *p5y*® *p6x* *p6y*) 
(compute-arrowhead-points) 
(multiple-value-bind (*p3x* *p3y* *p4x* *p4y®) 
(compute~arrow-shaft-points) 
(draw-big-outline)))) 


(defun compute-arrowhead-points () 

(let® ((plx (- *p0x* *top-edge*)) 
(ply *p0y*) 
(p2x (+ plx *top-edge-4*)) 
(p2y (- *p0y* *top-edge-4*)) 
(p6x *p0x*) 
(p6y (- *p0y* *top-edge*)) 
(p5x (- *p0x* *top-edge-4*) ) 
(p5y (+ p6by *top-edge-4*) )) 

(values plx ply p2x p2y p5x p5y p6x p6y))) 


(defun compute-arrow-shaft-points () 
(values (- *plx® *top-edge-4*) 
(- *p2y* *top-edge-2*) 
*p2x*® 
(- "p2y* *top-edge*) )) 


(defun draw-big-outline () 
(send *dest* ’:show-lines 
sp0x® *p0y* *plx® *ply*® *p2x* *p2y* *p3x*® *p3y* 
*p4x* *p4y* *p5x* *p5y* *p6x* *p6y* *p0x*® *p0y*)) 


. Outline the largest of the small arrowheads. We can generate all the 


interior outlines in the figure by outlining only the heads of the small 
arrows. We first draw the largest of these arrowheads by analogy with our 
drawing the large arrow. We can use our function 
compute-arrowhead-points to calculate the coordinates of the vertexes. 
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First we need to halve the value of *top-edge* and bind new values for the 
coordinates of the top right point of the arrow. 


{defun draw-arrow-graphic (*top-edge*® *p0x* *p9y*) 

(let ((*top-edge-2% (// *top-edge* 2)) 

(*top-edge-4* (// *top-edge* 4))) 
(draw-big-arrow) 

(let ((*top-edge* *top-edge-2*) 

(*p0x* (- *p0x* *top-edge-2*)) 

(*p0y* (- *p0y* *top-edge-2*))) 
(do-arrows)))) 


(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4))) 
(draw-arrow) )) 


(defun draw-arrow () 
(multiple-value-bind 
(*plx*® *ply® *p2x* Sp2y® %p5x2 *p5y* *p6x* *pb6y*) 
(compute-arrowhead-points) 
(draw-outline))) 


(defun draw-outline () 
(send *dest* *:show-lines *p2x*® *p2y* *plx*® *ply* 
*p0x® *p0y* *p6x* *p6y* *p5x* *p5y*)) 


| (defun do-arrows () 


5. Outline the rest of the small arrows. Each small arrow has two inferior 
arrows beneath it. We modify our function do-arrows by adding two 
recursive function calls: one to draw the left-hand inferior of each superior 
arrow, and one to draw the right-hand inferior. We limit the levels of 
recursion by defining a constant, *max-depth*, and incrementing the 
variable *depth* on each call to do-arrows until *depth* equals 
*max-depth*. 


| (defvar *depth*® 0 
"Level of recursion for the current arrow") 


(defconst *max-depth* 7 
“Number of levels of recursion") 


(defun draw-arrow-graphic (*top-edge*® *p0x® *p0y*) 

(let ((*top-edge-2* (// *top-edge* 2)) 

(*top-edge-4* (// *top-edge* 4))) 
(draw-big-arrow) 

(let ((*top-edge* *top-edge-2*) 
(*pOx® (- *p0x* *top-edge-2*)) 
(*p0y* (- *p0y* *top-edge-2*)) 
| (*depth® 0)) 

(do-arrows)))) 
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(defun do-arrows () 
(when (< *depth*® *max-depth*) 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 
(draw-arrow) 
(let ((#depth® (1+ *depth*)) 
(*top-edge* *top-edge-2*) 
(*p0x* (+ *top-edge-4* (- *p0x* *top- edge*))) 
(*p0y* (- *p0y* *top-edge-4*) )) 
(do-arrows) ) 
(let ((*depth® (1+ *depth*)) 
(*top-edge* *top-edge-2*) 
(*p0x*® (- *p0x* *top-edge-4*)) 
(*p0y* (+ *top-edge-4* (- *p0y* *top-edge*)))) 
(do-arrows))))) 


6. Define a function we can call to produce the graphic. This function has to 
make an instance of screen-arrow-output, clear the screen, and call 
draw-arrow-graphic. The arguments to draw-arrow-graphic determine 
the size and placement of the figure. For now, we use estimates based on 
the dimensions, in pixels, of an LGP page. 


(defun do-arrow () 
(let ((*dest*® (make-instance ’screen-arrow-output) )) 
(send terminal-io °:clear-screen) 
(draw-arrow-graphic 1280 1800 1800))) 


We now have a simple working version of our program. We first compile 
our code (see section 3.1, page 62). We then use SELECT L to select a Lisp 
Listener. There we can evaluate (graphics:do-arrow) to run the program. 
We can avoid typing the package prefix by first using pkg-goto to make the 
current package graphics: 


(pkg-goto ’graphics) 


When we run the program, we generate a screen image of the arrow 
outlines. Figure 1 (page 18) shows the output of the program at this stage. 


These six steps illustrate a pattern of incremental program development: 


We make each function initially simple. We add new functions and edit old 
ones as tasks become more complex or refined. Facilities for keeping track 
of Lisp syntax (section 2.4, page 19) and for editing code (section 2. 8, 

page 49) encourage this incremental style. 


We compile, test, and debug code in sections as we write it. Many 
Symbolics programmers, for example, would test draw-arrow both before 
and after adding the recursive function calls. 
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Lisp Listener 1 


Figure 1. Program output with only the outlines of the arrows in the 
figure. 
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To support this incremental style, we must be able to check the syntax of 
our code, edit it, and compile it in sections. We discuss facilities for 
keeping track of Lisp syntax in the next section; techniques for editing code 
in section 2.8 (page 49); and methods of compiling and evaluating in 
chapter 3 (page 61). 


2.4 Keeping Track of Lisp Syntax 


Zmacs allows you to move easily through Lisp code and format it in a readable style. 
Commands for aligning code and features for checking for unbalanced parentheses can help you 
detect simple syntax errors before compiling. 


Zmacs facilities for moving through Lisp code are typically single-keystroke commands with 
c-m- modifiers. For example, Forward Sexp (c-m-F) moves forward to the end of a Lisp 
expression; End Of Definition (c~m-E) moves forward to the end of a top-level definition. 
Most of these commands take arguments specifying the number of Lisp expressions to be 
manipulated. In Atom Word Mode word-manipulating commands operate on Lisp symbol 
names; when executed before a name with hyphens, for example, Forward Word (m-F) places 
the cursor at the end of the name rather than before the first hyphen (see section 2.2.4, 
page 9). 


See the Lisp Machine Summary for a list of common Zmacs commands for operating on Lisp 
expressions. 


2.4.1 Comments 
You can document code in two ways: You can supply documentation 
strings for functions, variables, and constants (see section 2.6, page 28); and 
you can insert comments in the source code. You can retrieve 
documentation strings with Zmacs commands and Lisp functions 
(section 2.6, page 28). The Lisp reader ignores source-code comments. 
Although you cannot retrieve them in the same ways as documentation 
strings, they are essential to maintaining programs and useful in testing and 
debugging (see chapter 3, page 61, and chapter 4, page 71). 


Most source-code comments begin with one or more semicolons. Symbolics 
programmers follow conventions for aligning comments and determining the 
number of semicolons that begin them: 


¢ Top-level comments, starting at the left margin, begin with three semicolons. 
¢« Long comments about code within Lisp expressions begin with two 
semicolons and have the same indentation as the code to which they refer. 


e Comments at the ends of lines of code start in a preset column and begin 
with one semicolon. 


You can also use #| to begin a comment and |# to end one. The comment 
can extend for more than one line. You can nest #| and |# within longer 
comments. 
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Example 

Let’s add some comments to draw-arrow-graphic. We can write a top- 
level comment without regard for line breaks and then use Fill Long 
Comment (m-%) to fill it. We use e~3 to insert a comment on the current 
line. We use m-LINE to continue a long comment on the next line. 


3; This function controls the calculation of the coordinates of the 
3; endpoints of the lines that make up the figure. The three arguments 
333 are the length of the top edge and the coordinates of the top right 
$33; point of the large arrow. DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW 
333; to draw the large arrow and then calls DO-ARROWS to draw the smaller 
333 ones. 
(defun draw-arrow-graphic (*top-edge* *p0x* *p0y*) 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4))) 
(draw-big-arrow) ;Draw large arrow 
3; Length of the top-edge for the first small arrow is half the 
:; Tength for the large arrow. Bind new coordinates for the top 
3; right point of the small arrow. 
(let ((*top-edge*® *top-edge-2*) 
(*p0x*® (- *p0x* *top-edge-2*)) 
(*p0y* (- *p0y* *top-edge-2*)) 
(*depth*® 0)) 
(do-arrows)))) ;Draw small arrows 


Reference 

Indent For Comment (c-3 or m-3) Inserts or aligns a comment on the 
current line, beginning in the preset 
comment column. 


Kill Comment (c-m-; ) Removes a comment from the current 
line. 

Down Comment Line (m-N) Moves to the comment column on the 
next line. Starts a comment if none 
is there. 

Up Comment Line (m-P) Moves to the comment column on the 


previous line. Starts a comment if 
none is there. 


Indent New Comment Line (m-LINE) When executed within a comment, 
inserts a newline and starts a 
comment on the next line with the 
same indentation as the previous line. 


Fill Long Comment (m-%) When executed within a comment 
that begins at the left margin, fills the 
comment. 
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Set Comment Column (c-X 3) Sets the column in which comments 
begin to be the column that 
represents the current cursor position. 
With an argument, sets the comment 
column to the position of the previous 
comment and then creates or aligns a 
comment on the current line. 


2.4.2 Aligning Code 
Code that you write sequentially will remain properly aligned if you 
consistently press LINE (instead of RETURN) to add new lines. When you 
edit code, you might need to realign it. c-m-Q@ and c-m-‘ are useful for 
aligning definitions and other Lisp expressions. 


Reference 

Indent New Line (LINE) Adds a newline and indents as 
appropriate for the current level of 
Lisp structure. 


Indent For Lisp (TAB or c-m-TAB)  Aligns the current line. If the line is 
blank, indents as appropriate for the 
current level of Lisp structure. 


Indent Sexp (c~m-Q) Aligns the Lisp expression following 
the cursor. 
Indent Region (c-m-‘) Aligns the current region. 


2.4.3 Balancing Parentheses 
When the cursor is to the right of a close parenthesis, Zmacs flashes the 
corresponding open parenthesis. The flashing open parentheses, along with 
proper indentation, can indicate whether or not parentheses are balanced. 
Improperly aligned code (after you use a c-m-Q command, for instance) is 
often a sign of unbalanced parentheses. 


To check for unbalanced parentheses in an entire buffer, use Find 
Unbalanced Parentheses (m-X). Zmacs can check source files for 
unbalanced parentheses when you save the files. If a file contains 
unbalanced parentheses, Zmacs can notify you and ask whether or not to 
save the file anyway. To put this feature into effect, place the following 
code in an init file: 


(login-forms 
(setq zwei: *check-unbalanced-parentheses-when-saving*® t)) 
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Reference 

Find Unbalanced Parentheses (a-X%) Searches the buffer for unbalanced 
parentheses. Ignores parentheses in 
comments and strings. 


2.5 Program Development: Drawing Stripes 


So far the sample program outlines all the arrows in the figure. The next task is to draw the 
diagonal stripes. To keep this stage as simple as possible, we ignore the differences in spacing 
and thickness of lines in the figure. We draw each stripe from upper left to lower right. We 
draw the stripes in five steps: 


1. Determine the distance between stripes. We first define a constant, 
*do-the-stripes*, that we bind to t when we want to draw stripes and nil 
when we want only outlines. We define another constant, 
*stripe-distance*, to contain the horizontal distance between stripes. Let’s 
assume we want 64 stripes in the large arrowhead. We divide the initial 
*top-edge* by 64 to obtain *stripe-distance*. 


(defconst *do-the-stripes* t 
“When t, permits striping of the figure®) 
(defconst *stripe-distance*® nil 
“Horizontal distance between stripes in the large arrow") 


(defun draw-arrow-graphic (*top-edge*® *p0x* *p0y*) 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4)) 
3; Compute horizontal distance between stripes in the 
3; large arrow, assuming 64 stripes in the large 
$3; arrowhead. 
(*stripe-distance*® (// *top-edge® 64))) 
(draw-big-arrow) ;Draw large arrow 
3; Length of the top-edge for the first small arrow is half the 
3; length for the large arrow. Bind new coordinates for the top 
33; right point of the small arrow. 
(let ({*top-edge* *top-edge-2*) 
(*p0x* (- *p0x® *top-edge-2*)) 
(*p0y* (- *p0y* *top-edge-2*)) 
(*depth*® 0)) 
(do-arrows)))) ;Draw small arrows 


2. Stripe the head of the large arrow. We define a function, 
stripe-arrowhead, and call it from draw-big-arrow. The function loops to 
calculate the coordinates of the endpoints of the stripes, starting in the 
upper right corner and decrementing x and y by *stripe-distance’*. 
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(defun draw-big-arrow () 

3; Determine coordinates of arrowhead vertexes 

(multiplte-value-bind 
(*plx*® *ply® *p2x* *p2y* *#p5x*® *p5y* *p6x*® *p6y*) 

(compute-arrowhead-points) 
3; Determine coordinates of shaft vertexes 
(multiple-value-bind (*p3x* *p3y* *p4x* *p4y*) 
(compute-arrow-shaft-points) 


(draw-big-outline) sOutline arrow 
(when *do-the-stripes* 
(stripe-arrowhead))))) ;Stripe head 


333 Function to control striping the head of each arrow. 
33; Determines coordinates of starting and ending points for each 
333 stripe. Calls DRAW-ARROWHEAD-LINES to draw each stripe. 
(defun stripe-arrowhead () 
33; Find x-coord of top of last stripe to be drawn 
(loop with last-x = (- *pO0x* *top-edge*) 
3; Find starting x-coord for each stripe, decrementing 
3; by distance between stripes. Stop at last x-coord. 
for start-x from *p0x* by *stripe-distance*® above last-x 
33; Find ending y-coord for each stripe, decrementing by 
3; distance between stripes. 
for end-y downfrom *pO0y® by *stripe-distance*® 
;; Draw a stripe 
do (draw-arrowhead-lines start-x end-y))) 


33; Draws a stripe in an arrowhead. Arguments are the x-coord 
333; of the starting point and the y-coord of the ending point 
33; of a stripe. 
(defun draw-arrowhead-lines (start-x end-y) 

(send *dest* *’:show-lines start-x *pOy*® *p0x* end-y)) 


3. Stripe the exposed portions of the shaft of the large arrow. The shaft 
consists of a series of descending triangles along the left and right sides. 
We define a function, stripe-big-arrow-shaft, to control the striping. We 
then define six functions, three to stripe the left side and three to stripe the 
right. The first function for each side iterates through the triangles that 
make up the shaft. The second function stripes one triangle. The third 
function draws one stripe. 
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(defun draw-big-arrow () 

3; Determine coordinates of arrowhead vertexes 

(multiple-value-bind 
(*plx® *ply*® *p2x*® *p2y* *p5x*® sp5y* *p6x*® ep6y*) 

(compute-arrowhead-points) 
3; Determine coordinates of shaft vertexes 
(multiple-value-bind (*p3x* *p3y* *p4x* *p4y*) 
(compute-arrow-shaft-points) 


(draw-big-out line) ;Outline arrow 
(when *do-the-stripes*® 
(stripe-arrowhead) ;Stripe head 
(stripe-big-arrow-shaft))))) sStripe shaft 


333; Function to control striping the shaft of the large arrow. 
333; Just calls STRIPE-BIG-ARROW-SHAFT-LEFT to stripe the left side 
333 and STRIPE-BIG-ARROW-SHAFT-RIGHT to stripe the right side. 
(defun stripe-big-arrow-~shaft () 

(stripe-big-arrow-shaft-left) 

(stripe-big-arrow-shaft-right)) 


33; Function to control striping left side of big arrow’s shaft. 
33; Iterates over the triangles that make up the shaft. Determines 
333; coordinates of the apex and bottom right point of each triangle. 
333 Calls DRAW-BIG-ARROW-SHAFT-STRIPES-LEFT to stripe each triangle. 
(defun stripe-big-arrow-shaft-left () 
3; Set up a counter for depth. Don’t exceed maximum recursion 
33 level. 
(loop for shaft-depth from 0 below *max-depth*® 
3; Find current top edge and its fractions 
for top-edge = *top-edge* then (// top-edge 2) 
for top-edge-2 = (// top-edge 2) 
for top-edge-4 = (// top-edge 4) 
33 Find coordinates of apex of triangle 
for apex-x = *p2x* then (- apex-x top-edge-2) 
for apex-y = *p2y* then (- apex-y top-edge-2) 
33; Find x-coord of bottom right vertex 
for right-x = (+ apex-x top-edge-4) 
3; Find y-coord of bottom edge of triangle 
for bottom-y = (- apex-y top-edge-4) 
3; Stripe each triangle 
do (draw-big-arrow-shaft-stripes-left 
top-edge-4 apex-x apex-y right-x bottom-y) )) 
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; Stripes each triangle in left side of big arrow’s shaft. 
; Arguments are one-fourth current top edge, x- and y-coords 
333 Of apex of triangle, x- and y-coords of bottom right vertex. 
3; Determines coordinates of starting and ending points for 
33; each stripe. Calls DRAW-BIG-ARROW-SHAFT-LINES-LEFT to 
333; draw the lines that make up each stripe. 
(defun draw-big-arrow-shaft-stripes-teft 
(top-edge-4 apex-x apex-y right-x bottom-y) 
(loop with half-distance = (// *stripe-distance* 2) 
3; Find x-coord of last stripe in triangle 
with last-x = (- apex-x top-edge-4) 
3; Find x-coord of top of each stripe, decrementing 
3; from the apex by HALF the horizontal distance 
3; between stripes. Stop at last stripe. 
for start-x from apex-x by half-distance above last-x 
3; Find y-coord of top of stripe 
for start-y downfrom apex-y by half-distance 
3; Find x-coord of endpoint of stripe 
for end-x downfrom right-x by *stripe-distance* 
3; Draw a stripe 
do (draw-big-arrow-shaft-lines-left 
start-x start-y end-x bottom-y))) 


33; Draws a stripe on the left side of the big arrow’s shaft. 
333; Arguments are the coordinates of the starting and ending 
333 points of each stripe. 
(defun draw-big-arrow-shaft-lines-left 
(start-x start-y end-x end-y) 
(send *dest* °*:show-lines 
start-x start-y end-x end-y)) 


333 Function to control striping right side of big arrow’s shaft. 
333 Iterates over the triangles that make up the shaft. Determines 
333; coordinates of the top point of each triangle. Calls 
333; DRAW-BIG-ARROW-SHAFT-STRIPES-RIGHT to stripe each triangle. 
(defun stripe-big-arrow-shaft-right () 
3; Set up a counter for depth. Don’t exceed maximum recursion 
33; level. 
(loop for shaft-depth from 0 below *max-depth*® 
33; Find new top edge and its fractions 
for top-edge = *top-edge* then (// top-edge 2) 
for top-edge-2 = (// top-edge 2) 
for top-edge-4 = (// top-edge 4) 
3; Find coords of top point of triangle 
for start-x = (+ *"p2x*® top-edge-4) 
for top-y = (- *p2y* *top-edge-4*) 
then (- top-y top-edge-2 top-edge-4) 
3: Stripe the triangle 
do (draw-big-arrow-shaft-stripes-right 
top-edge-2 top-edge-4 start-x top-y))) 
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333; Stripes each triangle in right side of big arrow’s shaft. 
333; Arguments are one-half and one-fourth of current top edge, and 
33; coords of top point of the triangle. Determines coordinates of 
333 Starting and ending points for each stripe. Calls 
333; DRAW-BIG-ARROW-SHAFT-LINES-RIGHT to draw a stripe. 
(defun draw-big-arrow-shaft-stripes-right 
(top-edge-2 top-edge-4 start-x top-y) 
(loop with half-distance = (// *stripe-distance*® 2) 
3; Find y-coord of last stripe in triangle 
with last-y = (- top-y top-edge-2) 
3; Find y-coord of starting point of stripe. Don’t go 
3; past the end of the triangle. 
for start-y from top-y by *stripe-distance* above last-y 
3; Find coords of ending point of the stripe, decrementing 
33; by HALF the horizontal distance between stripes 
for end-x downfrom (+ start-x top-edge-4) by half-distance 
for end-y downfrom (- top-y top-edge-4) by half-distance 
3; Draw a stripe 
do (draw-big-arrow-shaft-lines-right 
start-x start-y end-x end-y))) 


33;; Draws a stripe on the right side of the big arrow’s shaft. 
33; Arguments are the coordinates of the starting and ending points 
33; of the. stripe. 
(defun draw-big-arrow-shaft-lines-right 
(start-x start-y end-x end-y) 
(send *dest® ’:show-lines 
start-x start-y end-x end-y)) 


. Stripe the heads of the small arrows. We call stripe-arrowhead from 
draw-arrow. 


(defun draw-arrow (). 
3; Calculate coordinates of arrowhead vertexes 
(multiple-value-bind 
(*plx® *ply® *p2x* *p2y* *p5x* *p5y* *pé6x* *pb6y*) 
(compute-arrowhead-points) 


(draw-out line) sOutline arrowhead 
(when *do-the-stripes® 
(str ipe-arrowhead)))) ;Stripe head 


. Stripe the exposed shafts of the small arrows. Like the shaft of the large 
arrow, these shafts are composed of a series of descending triangles. We 
define three functions: stripe-arrow-shaft iterates through the triangles 
that make up a shaft; draw-arrow-shaft-stripes stripes one triangle; and 
draw-arrow-shaft-lines draws one stripe. We call stripe-arrow-shaft from 
draw-arrow. 
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(defun draw-arrow () 
3; Calculate coordinates of arrowhead vertexes 
(multiple-value-bind 
(*plx*® *ply*® *p2x*® *p2y* *p5x*® *p5y* *p6x® *poy*) 
(compute-arrowhead-points) 


(draw-out line) ;Outline arrowhead 
(when *do-the-stripes* 

(str ipe-arrowhead) ;Stripe head 

(str ipe-arrow-shaft)))) sStripe shaft 


; Function to contro! striping the shaft of a smal) arrow. 
; Iterates over the descending triangles that make up the shaft. 
Calculates the coordinates of the top left and bottom right 
; vertexes of each triangle. Calls DRAW-ARROW-SHAFT-STRIPES to 
333 stripe each triangle. 
(defun stripe-arrow-shaft () 

3; Set up a counter for depth. Don’t exceed maximum 

3; recursion level. 

(loop for shaft-depth from *depth*® below *max-depth* 
3; Calculate fractions of new top edge 
for top-edge-2 = *top-edge-2* then (// top-edge-2 2) 
for top-edge-4 = (// top-edge-2 2) 
3; Find coords of top left point of triangle 
for left-x = *p2x® then (- left-x top-edge-4) 
for top-y = *p2y* then (- top-y top~-edge-2 top-edge-4) 
s; Find coords of bottom right point of triangle 
for right-x = (+ left-x top-edge-2) 
for bottom-y = (- top-y top-edge-2) 
3; Stripe the triangle 
do (draw-arrow-shaft-stripes 

left-x top-y right-x bottom-y))) 


eo we we we 
we we we we 
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333; Stripes each triangle in the shaft of a small arrow. 
33; Arguments are coordinates of the top left and bottom 
:3; right points of the triangle. Calculates the y-coord 
333 of the starting point and the x-coord of the ending point 
333 of each stripe. Calls DRAW-ARROW-SHAFT-LINES to draw the 
333 stripe. 
(defun draw-arrow-shaft-stripes 
(left-x top-y right-x bottom-y) 
33; Find y-coord of starting point of stripe. Don’t go 
3; below the bottom of the triangle. 
{loop for start-y from top-y by *stripe-distance*® above bottom-y 
3; Find x-coord cf ending point of the stripe 
for end-x downfrom right-x by *stripe-distance* 
3; Draw a stripe 
do (draw-arrow-shaft-lines 
left-x start-y end-x bottom-y))) 
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333; Draws a stripe in the shaft of a small arrow. Arguments are 
333 the coordinates of the starting and ending points of the 
si3 stripe. 
(defun draw-arrow-shaft-lines 
(left-x start-y end-x bottom-y) 
(send *dest* °:show-lines 
left-x start-y end-x bottom-y)) 


Figure 2 (page 29) shows the output of the program, with stripes of even spacing and thickness. 


This stage in program development differs from the beginning of the program in two ways: 


e As we add new functions, we need to refer to existing code for such 
information as the order of arguments in argument lists and the values of 
variables and constants (section 2.6, page 28). 

e We must start to change existing code, adding function calls and new 
arguments. These changes require increasing use of facilities for editing 
code (section 2.8, page 49). . 


2.6 Finding Out About Existing Code 


When you write or edit programs, you often need to find characteristics of existing code. If 
you write programs incrementally, you need to find existing definitions, argument lists, and 
values. To maintain modularity, you must know how new code should interact with previously 
written modules. If you want to incorporate parts of the Lisp Machine system in your 
programs, you often have to refer to system source code. 


Zmacs and Zetalisp have many facilities for retrieving information about Lisp objects and for 
displaying and editing source code. This section describes features especially useful for writing 
and editing code. We discuss facilities for learning about Lisp objects, symbols, variables, 
functions, and pathnames. 


2.6.1 Objects 
describe displays information about a Lisp object in a form that depends 
on the object’s type. For example, for a special variable, describe displays 
the value, package, and properties, including documentation, pathname of 
the source file, and Zmacs buffer sectioning node. 


An interactive, window-oriented version of describe is the Inspector (see 
section 4.7, page 94). 


describe does not display array elements. For that you can use the 
Inspector or listarray. 


Example 


(describe °*top-edge*) 
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The value of *TOP-EDGE* is NIL 
*TOP-EDGE* is in the GRAPHICS package. 
*TOP-EDGE* has property DOCUMENTATION: 
“Length of the top edge of the arrow" 
*TOP-EDGE* has property SPECIAL: 
#<UNIX-PATHNAME "VIXEN: //dess//doc//workstyles//pcodex.#"> 
#<UNIX-PATHNAME “VIXEN: //dess//doc//workstyles//pcodex.#">, 
an object of flavor FS:UNIX-PATHNAME, 
has instance variable values: . 


FS:HOST: #<UNIX-CHAOS-HOST SCRC-VIXEN> 

FS:DEVICE: : UNSPECIFIC 

FS:DIRECTORY: ("dess" “doc" “workstyles") 

FS: NAME: *pcodex" 

FS: TYPE: WIL 

FS: VERSION: : UNSPECIFIC 

SI: PROPERTY-LIST: (BASE 10 :MODE ...) 

FS:STRING-FOR-PRINTING: “VIXEN: //dess//doc//workstyles//pcodex.#" 
FS:STRING-FOR-HOST: "//dess//doc//workstyles//pcodex.#" 


FS:STRING-FOR-EDITOR: NIL 
FS:STRING-FOR-DIRED: NIL 
FS:STRING-FOR-DIRECTORY: NIL 


*TOP-EDGE* has property SOURCE-FILE-NAME: 
((DEFVAR #<UNIX-PATHNAME 
“VIXEN: //dess//doc//workstyles//pcodex.#">) ) 
((DEFVAR #<UNIX-PATHNAME 
"VIXEN: //dess//doc//workstyles//pcodex.#">)) is a list 


*TOP-EDGE*® has property ZWEI:ZMACS-BUFFERS: 
((DEFVAR #<SECTION-NODE Variable *TOP-EDGE* 27316607>)) 
((DEFVAR #<SECTION-NODE Variable *TOP-EDGE* 27316607>)) is a list 


*TOP-EDGE* 

Reference 

(describe object) Displays information about objecr in a 
form that depends on the object’s 
type. For named structures, displays 
the symbolic names and contents of 
the entries in the structure. 

(listarray array) Returns a list whose elements are the 


elements of array. 


2.6.2 Symbols 
Several Zmacs commands and Lisp functions find the name of a symbol or 
retrieve information about it. Unless you specify a package, most of these 
commands search the global package and its inferiors. It now takes several 
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minutes to search all these packages; if you don’t know which one the 
symbol is in, you might want to use functions like apropos and who-calls 
only as a last resort. (See Program Development Help Facilities for more on 
the meanings and default values of arguments to these functions.) 


Example 

In defining the function stripe-big-arrow-sheft-left, we need to use the 
constant *max-depth*, but we remember only that its name contains 
"depth". We use either m-ESCAPE (to evaluate a form in the editor 
minibuffer) or SELECT L (to select a Lisp Listener) and then evaluate: 


(apropos "depth" "’graphics) 


GRAPHICS: DEPTH 

GRAPHICS: *MAX-DEPTH*® - Bound 

GRAPHICS: SHAFT-DEPTH 

GRAPHICS: *DEPTH* - Bound 

(*DEPTH® SHAFT-DEPTH *MAX-DEPTH*® DEPTH) 


Example 
After compiling stripe-arrowhead we want to test the program as written 
so far, but we forget which function calls draw-arrow-graphic: 


(who-calls °draw-arrow-graphic ’graphics) 


DO-ARROW calls DRAW-ARROW-GRAPHIC as a function. 
(DO-ARROW) 


You can also find the callers of a function with List Callers (m-) (see 
section 2.6.4, page 33). 


Reference 

(apropos string package inferiors superiors) 
Displays the names of all symbols 
whose names contain string. Indicates 
whether or not the symbol is bound. 
Displays argument lists of functions. 


Where Is Symbol (m-) Displays the names of packages that 
contain the specified symbol. 

(where-is string package) Displays the names of packages that 
contain a symbol whose print name is 
string. 


(who-calls symbol package inferiors superiors) 
Displays information about uses of 
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symbol as function, variable, or 
constant. Returns a list of the names 
of callers of symbol. 


(what-files-call symbol package) Displays names of files that contain 
uses of symbol as function, variable, 
or constant. 


(plist symbol) | . Returns the list representing the 
property list of symbol. 


List Matching Symbols (m-X) Displays the names of symbols for 

which a predicate lambda-expression 
_ returns something other than nil. 

Prompts for a predicate for the 
expression (lambda (symbol) 
predicate). By default, searches the 
current package; with an argument of 
c-U, searches all packages; with an 
argument of c-U c-U, prompts for 
the name of a package. Press c-. to 
edit definitions of symbols that satisfy 
the predicate. 


Describe Variable At Point (c-sh-V) is a useful command to display 
information about a variable. It tells you whether or not the variable is 
bound, whether it has been declared special, and the file, if any, that 
contains the declaration. You can find the value of a variable by evaluating 
it in a Lisp Listener. If you have added a documentation string to the 
variable declaration, you can retrieve the string with c-sh-V or with 
e-sh-D, m-sh-D, or documentation (see section 2.6.4, page 33). 


Example 
In writing stripe-arrow-shaft we want to find out whether or not 
*max-depth* is bound. c-sh-¥V displays the following information: 


*MAX-DEPTH*® has a value and is declared special by file 
VIXEN: /dess/doc/workstyles/pcodex.1 
Number of levels of recursion 


‘Reference 

Describe Variable At Point (c-sh-V) Indicates whether or not the variable 
is declared special, is bound, or is 
documented by defvar or defconst. 
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2.6.4 Functions 
Many Zmacs and Zetalisp facilities for finding out about functions apply 
both to functions defined by defun and to objects defined by other special 
forms and macros that begin with "def". 


2.6.4.1 Definitions 


Edit Definition (m-.) is a powerful command to find and edit definitions of 
functions and other objects. It is particularly valuable for finding source 
code, including system code, that is stored in a file other than that 
associated with the current buffer. It finds multiple definitions when, for 
example, a symbol is defined as a function, a variable, and a flavor. It 
maintains a list of these definitions in a support buffer, where you can use 
m-. to return to the definitions even when you are finished editing. 


Section 5.2.2 (page 129) describes how to use Edit Definition (m-.) to edit 
definitions of flavor methods. 


Example 

We have written stripe-arrowhead and want to call it from 
‘draw-big-arrow. We use m-. to position the cursor at the definition of 
draw-big-arrow. 


Reference 

Edit Definition (m-. ) Selects a buffer containing a function 
definition, reading in the source file if 
necessary. You can specify a 
definition by typing the name into the 
minibuffer or clicking on a name 
already in the buffer. Offers name 
completion for definitions already in 
buffers. With a numeric argument, 
selects the next definition satisfying 
the most recently specified name. 


2.6.4.2 Names 


Often you know only part of a function name and need to find the 
complete name. Use Function Apropos (m-%). 


Example . 

We want to call stripe-arrowhead from draw-arrow, but we remember 
only that draw-arrow contains the string "arrow". We use Function 
Apropos (m-%) to display the names of functions that contain "arrow". We 
click left on the name draw-arrow to edit its definition. 
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m-X Function Apropos arrow 


Functions matching arrow: 
DO-ARROW 

DO-ARROWS 

DRAW-ARROW 

DRAW-ARROW-GRAPHIC 
DRAW-ARROWHEAD-LINES 
DRAW-BIG-ARROW 
DRAW-BIG-ARROW-SHAFT-LINES-LEFT 
DRAW-BIG-ARROW-SHAFT-LINES-RIGHT 
DRAW-BIG-ARROW-SHAFT-STRIPES-LEFT 
DRAW-BIG-ARROW-SHAF T-STRIPES-RIGHT 
STRIPE-ARROWHEAD 
STRIPE-BIG-ARROW-SHAFT 
STRIPE-BIG-ARROW-SHAFT-LEFT 
STRIPE-BIG-ARROW-SHAF T-RIGHT 


Reference 

Function Apropos (m-%) Displays the names of functions that 
contain a string. Press c~. or click 
left on names in the display to edit 
the definitions of the functions listed. 


2.6.4.3 Documentation 


Function definitions can include documentation strings. When you need to 
know the purpose of the function, you can retrieve the documentation with 
e-sh-D, m-sh-D, or documentation. 


Example 

We wrote a long source-code comment at the beginning of the definition of 
draw-arrow-graphic. We could have made this comment a documentation 
string: 
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(defun draw-arrow-graphic (*top-edge* *p0x* *p0y*) 
“Function controlling the calculation module. 
Controls calculation of the coordinates of the endpoints of the lines 
that make up the figure. The three arguments are the length of the top 
edge and the coordinates of the top right point of the large arrow. 
DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW to draw the large arrow and then 
calls DO-ARROWS to draw the smaller ones." 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4)) 
3; Compute horizontal distance between stripes. in the 
3; large arrow, assuming 64 stripes in the large 
33 arrowhead. 
(*stripe-distance*® (// *top-edge* 64))) 
(draw-big-arrow) 3;Draw large arrow 
3; Length of the top-edge for the first small arrow is half the 
3; length for the large arrow. Bind new coordinates for the top 
3; right point of the small arrow. 
(let ((*top-edge*® *top-edge-2*) 
(*p0x*® (- *p0x® *top-edge-2*) ) 
(*p0y* (- *p0y* *top-edge-2*)) 
(*depth*® 0)) 
(do-arrows)))) sDraw small arrows 


Later, when defining do-arrow, we add a call to draw-arrow-graphic. We 
want to be sure that this is the control function for the calculation module. 
We position the cursor at the name draw-arrow-graphic inside the 
definition of do-arrow and use m-sh-D to display the documentation string 
for draw-arrow-graphic: 


DRAW-ARROW-GRAPHIC: (*TOP-EDGE*® *POX*® *POY*) 

Function controlling the calculation module. 

Controls calculation of the coordinates of the endpoints of the lines 
that make up the figure. The three arguments are the length of the top 
edge and the coordinates of the top right point of the large arrow. 
DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW to draw the large arrow and then 
calls DO-ARROWS to draw the smaller ones. 


e-sh-D displays the first line of the documentation string: 


DRAW-ARROW-GRAPHIC: Function controlling the calculation module. 


To ensure that c-sh-D displays meaningful information, make the first line 
of each documentation string a complete sentence that summarizes the 
function. 


Reference 
Brief Documentation (c-sh-D) Displays the first line of the 
function’s documentation string. 
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Long Documentation (m-sh-D) Displays the function’ s documentation 
string. 

(documentation function) Displays the function’s documentation 
string. 


2.6.4.4 Argument Lists 


Quick Arglist (c-sh-A) and arglist retrieve the argument list for a 
function. What these facilities display depends on the nature of the 
function, whether or not it has been compiled, and what options the 
function includes; see the Lisp Machine Manual, section 10.9, page 150, and 
Program Development Help Facilities for details. 


Example 

We are editing the definition of do-arrow to add a cali to 
draw-arrow-graphic. We want to see the argument list for 
draw-arrow-graphic. We position the cursor at the name 
draw-arrow-graphic in the definition of do-arrow and use c~sh-A: 


DRAW-ARROW-GRAPHIC: (*TOP-EDGE*® *POX* *POY*) 


Reference 

Quick Arglist (e-sh-A) _ Displays a representation of the 
argument list of the current function. 
With a numeric argument, you can 
type the name of the function into 
the minibuffer or click on a function 
name in the buffer. 


(arglist function) Displays a representation of the 
| function’s argument list. 


2.6.4.5 Callers 


When you change a function definition, you sometimes need to make 
complementary changes in the function’s callers. Four Zmacs commands 
find the callers of a function. These commands, like who-calls, now take 
several minutes to search all packages for callers. (For the example 
program, we need to search only the graphics package.) By default, these 
commands search the current package. With an argument of c-U, they 
search all packages. You can specify the packages to be searched by giving 
the commands an argument of c-U ¢-U. 


Example | ; 
We decide to change the order of the arguments to draw-arrow-graphic. 
We want to be sure to change all the callers of draw-arrow-graphic to call 
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the function with arguments in the correct order. We use Edit Callers 


(m-%). 
Reference | 
List Callers (m-X) Lists functions that call the specified 
function. Press c-. to edit the 
definitions of the functions listed. 
Multiple List Callers (m-X) Lists functions that call the specified 
functions. Continues prompting for 
function names until you press only 
RETURN. Press c-. to edit the 
| definitions of the functions listed. 
Edit Callers (m-%) Prepares for editing the definitions of 
functions that call the specified 
function. Press c-. to edit 
| subsequent definitions.. 
Multiple Edit Callers (m-X) Prepares for editing the definitions of 


functions that call the specified 
functions. Continues prompting for - 
function names until you press only. 
RETURN. Press c-. to edit subsequent 
definitions. 


2.6.5 Pathnames . 
Zmacs provides several ways of finding the name of a file. If you just need 
the name of a file and have some idea what directory it is in, you can use 
e-% c-D with an argument of c-U or View Directory (m-) to display a 
directory. If you want to operate on files in a directory, you can use c-X D 
with an argument of c-U or Dired (m-X) to edit a directory. If you want 
to find a source file but don’t know what directory it is in, you might 
remember the name of a function defined in the file. In that case, you 
might be able to use m-. to find the file. 


Example 

After editing the definitions in the calculation module, we want to find the 
output module to edit the definition of do-arrow. We forget the name of 

the file, but we remember the name of the directory. We can use c-U c-X 
c-D to display the directory. If we have interned do-arrow or read its file 
into a buffer, we can use m-. to find do-arrow directly. 


Reference 

Display Directory (c-X c-D) Displays the current buffer’s file’s 
directory. With an argument of c-U, 
prompts for a directory to display. 
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Lists a directory. 


Edits the current buffer’s file’s 
directory. With an argument of c-U, 
prompts for a directory to edit. 
Displays the files in the directory. 
You can use single-character 
commands to operate on the files. 


Edits a directory. Displays the files 
in the directory. You can use single- 
character commands to operate on the 
files. 


2.7 Program Development: Refining Stripe Density and Spacing 


At this stage of development, the program outlines the arrows in the figure and fills them with 
stripes of uniform thickness and spacing. In the finished figure, stripe thickness or density 
increases from upper right to lower left within each arrow, and stripe spacing varies among the 
levels of the figure. We adjust the stripe spacing by replacing the constant distance between 
stripes by a variable. We correct the stripe density by drawing multiple adjacent lines for each 


stripe. 


We adjust the stripe spacing in three steps: 


1. Define a variable, *stripe-d*, to represent the distance between stripes for 


each arrow. 


(defvar *stripe-d* nil 


"Horizontal distance between stripes for each arrow") 


2. Calculate the value of *stripe-d* for each arrow. For the large arrow, this 
is just *stripe-distance*. For the small arrows, we need to call a new 
function, compute-stripe-d, from draw-arrow. compute-stripe-d calculates 
*“stripe-d* as a fraction of *stripe-distance* that depends on the level of 
recursion. It ensures that *stripe-d* divides *top-edge* evenly and that 


*stripe-d* is never less than 3. 
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(defun draw-big-arrow () 
3; Determine coordinates of arrowhead vertexes 
(mu ltiple-value-bind 
(*plx*® *ply* *p2x*® tp2y® *p5x2 *p5y® *p6x*® *p6y*) 
(compute-arrowhead-points) 
3; Determine coordinates of shaft vertexes 
(multiple-value-bind (*p3x* *p3y* *p4x* *p4y*) 
(compute-arrow-shaft-points) 
(draw-big-outline) sOutline arrow 
(when *do-the-stripes*® 
3; Bind distance between stripes 
(let ((*stripe-d* *stripe-distance*) ) ; 
(str ipe-arrowhead) sStripe head 
(stripe-big-arrow-shaft)))))) sStripe shaft 


(defun draw-arrow () 
33; Calculate coordinates of arrowhead vertexes 
(multiple-value-bind 
(*plx* *ply* *p2x*® *p2y* *p5x® Sp5y® *p6x* *p6y*) 
(compute-arrowhead-points) 
(draw-out line) ;Outline arrowhead 
(when *do-the-stripes*® 
3; Calculate distance between stripes 
(let ((*stripe-d* (compute-stripe-d))) 
(str ipe-arrowhead) ;Stripe head 
(stripe-arrow-shaft))))) s;Stripe shaft 
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33; Calculates horizontal distance between stripes. 
33; Distance is a fraction of the distance between stripes for the 
333 large arrow. The divisor depends on the level of recursion. 
33; Distance divides length of top edge evenly when possible to 
333 maintain continuity between head and shaft of arrow. 
(defun compute-stripe-d () 
3; Distance should be at least 3 pixels so that there is some 
3; white space between lines. 
(if (< *stripe-distance*® 3) 
3 
3; First find a fraction of *STRIPE-DISTANCE*® that depends 
33; on recursion level 
(loop for dist = (fixr (// *stripe-distance® . 
(selectq *depth# 
(0 2) 
(1 4) 
(2 2) 
(3 1.5) 
(4 1.5) 
(otherwise 2)))) 
3; Increment if it doesn’t divide *TOP-EDGE* evenly 
then (1+ dist) 
when (= 0 (\ *top-edge* dist)) 
3; Stop when no remainder. Don’t return a value 
3; less than 3. 
do (return (if (<s dist 3) 3 dist))))) 


3. Replace *stripe-distance* with *stripe-d* in the functions 
stripe-arrowhead and draw-arrow-shaft-stripes. 


(defun stripe-arrowhead () 

3; Find x-coord of top of last stripe to be drawn 

(loop with last-x = (- *p0x*® *top-edge*) 
3; Find starting x-coord for each stripe, decrementing 
33; by distance between stripes. Stop at last x-coord. 
for start-x from *p0x* by *stripe-d* above last-x 
3; Find ending y-coord for each stripe, decrementing by 
3; distance between stripes. 
for end-y downfrom *p0y* by *stripe-d* 
3; Draw a stripe 
do (draw-arrowhead-lines start-x end-y))) 
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(defun draw-arrow-shaft-stripes 
(left-x top-y right-x bottom-y) 
33; Find y-coord of starting point cf stripe. Don’t go 
33 below the bottom of the triangle. 


| (loop for start-y from top-y by *stripe-d*® above bottom-y 
33 Find x-coord of ending point of the stripe 
| for end-x downfrom right-x by *stripe-d* 


3; Draw a stripe 
do (draw-arrow-shaft-lines 
left-x start-y end-x bottom-y))) 


We adjust the stripe density in three steps: 


1. Define two new constants for each. arrow, *d1* and *d2*. *d1* represents 
the stripe density, or the proportion of the distance between stripes that is 
black, at the upper right of each arrow. *d2* represents the density at 
lower left for each arrow. We estimate *d1* to be 0.15 and *d2* to be 
0.75. 


(defconst *d1* 0.15 
“Proportion of distance between upper right stripes that is bl k") 


(defconst *d2* 0.75 
“Proportion of distance between lower left stripes that is black") 


2. Define a function, compute-nlines, that returns the number of adjacent 
lines that make up a stripe to be drawn. This function calls another, 
compute-dens, to calculate the proportion of the distance between stripes 
that is black. This proportion is a function of the position of the stripe 
between the upper. right and lower left of the arrow. compute-nlines 
multiplies this proportion by *stripe-d* to determine the number of lines 
that make up the stripe. This number must be at least one and less than 
*stripe-d* minus one. 


The argument to compute-nlines represents the horizontal position of the 
stripe to be drawn between the upper right and lower left of the arrow. 
Imagine the top edge of each arrow projected to the left beyond the 
arrowhead. Imagine each stripe projected to the upper left until it 
intersects with the extended top edge. The argument to compute-nlines is 
the x-coordinate of this intersection. *pOx* is the x-coordinate of this 
intersection for the top right corner of each arrow, where the stripe density 
is *d1*. *x2* is the x-coordinate of this intersection for the lower left 
stripe in each arrow, where the density is *d2*. The x-coordinate for each 
stripe must be between *p0x* and *x2*, and the density must be between 
*d1* and *d2*. 


(defvar *x2* nil 
"X-coordinate of projection of lower left stripe on top edge") 
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(defun draw-big-arrow () 
:; Determine coordinates of arrowhead vertexes 
(multiple-value-bind 
(*plx*® *ply* *p2x* *p2y* *p5x*® tp5y* *p6x* *p6y*) 
(compute-arrowhead-points) 
3; Determine coordinates of shaft vertexes 
(multiple-value-bind (*p3x* *p3y* *p4x* *p4y*) 
(compute-arrow-shaft-points) | 
(draw-big-outline) ;Outline arrow 
(when *do-the-stripes® 
3; Bind distance between stripes and x-coord of 
3; projection of last stripe onto top edge 
(let ((*stripe-d* *stripe-distance*) 


| (*x2® (- *p0x* *top-edge* *top-edge*) )) 
(str ipe-arrowhead) sStripe head 
(stripe-big-arrow-shaft)))))) ;Stripe shaft 


(defun draw-arrow () 
3; Calculate coordinates of arrowhead vertexes 
(multiple-value-bind 
(*plx® *ply® *p2x* *p2y* *p5x® *p5y* *p6x* *p6y*) 
(compute-arrowhead-points) 
(draw-outline) ;Outline arrowhead 
(when *do-the-stripes*® 
33 Calculate distance between stripes and x-coord of 
3; projection of last stripe onto top edge 
(let ((*stripe-d* (compute-stripe-d) ) 


| (*x2® (- "p0x* *top-edge*® *top-edge*) )) 
(str ipe-arrowhead) sStripe head 
(stripe-arrow-shaft))))) s;Stripe shaft 


333; Calculates the number of lines that compose each stripe. 
333 Calls COMPUTE-DENS to calculate the proportion of distance 
333 between stripes to be filled, then multiplies by the actual 
333; distance between stripes. Makes sure that there is at least 
333; one line and that there aren’t too many lines to leave some 
33; white space. 
(defun compute-nlines (x) 
3; Call COMPUTE-DENS and muitiply result by *stripe-d*# 
(let ((nl (fix (* *stripe-d* (compute-dens x))))) 
3; Supply at least one line 
(cond ((< nl 1) 1) 
3; But leave some white space between lines 
((2 nl (- *stripe-d* 1)) (- *stripe-d* 2)) 
(t ni)))) 


Program Development Tools and Techniques 43 


Symbolics, Inc. 


eee 
te oe 


Calculates proportion of distance filled in between each stripe. 

; The argument is the x-coordinate of the projection of the current 

; stripe onto the line formed by the top edge. Determines where the 
; projection of the current stripe is on this line in relation to the 
; distance from first to last stripes in the arrow. Multiplies this 
; fraction by the difference between densities of first and last 
stripes. Finally, adds the density of the first stripe. 


(defun compute-dens (x) 
(+ *d1* (* (- *d2* *d1*) 


(// (- x *p0x*) (float (- *x2* *p0x*)))))) 


3. For each function that draws a stripe, replace the sending of one 
:Show-lines message by a lcop that might send several. Determine the 
number of messages each function should send by calling compute-nlines. 


(defun stripe-arrowhead () 
3; Find x-coord of top of last stripe to be drawn 
(loop with last-x = (- *p0x* *top-edge*) 


3; Find starting x-coord for each stripe, decrementing 
3; by distance between stripes. Stop at last x-coord. 
for start-x from *p0x® by *stripe-d* above last-x 

3; Find ending y-coord for each stripe, decrementing by 
s; distance between stripes. 

for end-y downfrom *pOy* by *stripe-d* 

3; Find number of lines in the stripe 

for nlines = (compute-nlines start-x) 

3; Draw the lines that make up the stripe 

do (draw-arrowhead-lines nlines start-x end-y last-x))) 


(defun draw-arrowhead-lines (nlines start-x end-y last-x) 
3; Set up a counter 
(loop for i from.0 below nlines 


33; Find starting x-coord, subtracting counter from first 
33 xX-coord 
for first-x = (- start-x i) 
3;. Make sure we don’t go past the end of the arrowhead 
while (< last-x first-x) 
3; Draw a line 
do (send *dest*® *:show-lines 
first-x *pO0y* *p0x*® (- end-y i)))) 
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(defun stripe-big-arrow-shaft-left () 
3; Set up a counter for depth. Don’t exceed maximum recursion 
3; level. 
(loop for shaft-depth from 0 below *max-depth*® 
3; Find current top edge and its fractions 
for top-edge = *top-edge* then (// top-edge 2) 
for top-edge-2 = (// top-edge 2) 
for top-edge-4 = (// top-edge 4) 
3; Find coordinates of apex of triangle 
for apex-x = *p2x* then (- apex-x top-edge-2) 
for apex-y = *p2y* then (- apex-y top-edge-2) 
3; Find x-coord of bottom right vertex 
for right-x = (+ apex-x top-edge-4) 
3; Find y-coord of bottom edge of triangle 
for bottom-y = (- apex-y top-edge-4) 
3; Find the x~-coord of the projection of the first 
3; stripe onto top edge 
for xoff = (- *pO0x* *top-edge*) then (- xoff top-edge) 
3; Stripe each triangle 
do (draw-big-arrow-shaft-stripes-left 
top-edge-4 apex-x apex-y right-x bottom-y xoff))) 


(defun draw-big-arrow-shaft-stripes-left 
(top-edge-4 apex-x apex-y right-x bottom-y xoff) 
(loop with half-distance = (// *stripe-distance*® 2) 
3; Find x-coord of last stripe in triangle 
with last-x = (- apex-x top-edge-4) 
33; Find x-coord of top of each stripe, decrementing 
3; from the apex by HALF the horizontal distance 
3; between stripes. Stop at last stripe. 
for start-x from apex-x by half-distance above last-x 
3; Find y-coord of top of stripe 
for start-y downfrom apex-y by half-distance 
3; Find x-coord of endpoint of stripe 
for end-x downfrom right-x by *stripe-distance*® 
33; Find number of Yines in the stripe 
for nlines = (compute-nlines (- xoff (- right-x end-x))) 
3; Draw a stripe 
do (draw-big-arrow-shaft-lines-left 
nlines start-x start-y end-x bottom-y last-x))) 
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(defun draw-big-arrow-shaft-lines-left 


(nlines start-x start-y end-x end-y last-x) 


3; Set up two counters -- we need to draw two lines at once 
(loop for i from 0 


for i2 from 0 by 2 
3; Find x-coord of top of first line in stripe 
for first-x = (- start-x i) 
3; Don’t exceed number of lines in stripe 
while (< i2 nlines) 
3; Don’t go past the end of the triangle 
while (< last-x first-x) 
;; Draw a line 
do (send *dest* °:show-lines first-x (- start-y i) 
(- end-x i2) end-y) 

3; Draw a second line. The two lines are a refinement 
3; to stagger the endpoints of the lines so the diagonal 
3; edge looks neat. 
(send *dest*® °:show-lines first-x (- start-y i 1) 

(- end-x i2 1) end-y))) 


(defun stripe-big-arrow-shaft-right () 

3; Set up a counter for depth. Don’t exceed maximum recursion 
level. 
(loop for shaft-depth from 0 below *max-depth*® 


3; Find new top edge and its fractions 
for top-edge = *top-edge* then (// top-edge 2) 
for top-edge-2 = (// top-edge 2) 
for top~edge-4 = (// top-edge 4) 
3; Find coords of top point of triangle 
for start-x = (+ *"p2x* top-edge-4) 
for top-y = (- *p2y* *top-edge-4*) 
then (- top-y top-edge-2 top-edge-4) 
3; Find x-coord of projection of first stripe onto 
33 top-edge 
for xoff = (- *p0x*® *top-edge*) then (- xoff top-edge) 
3; Stripe the triangle 
do (draw-big-arrow-shaft-stripes-right 
top-edge-2 top-edge-4 start-x top-y xoff))) 
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(defun draw-big-arrow-shaft-stripes-right 
(top-edge-2 top-edge-4 start-x top-y xoff) 
(loop with half-distance = (// *stripe-distance* 2) 

- 33 Find y-coord of last stripe in triangle 

with last-y = (- top-y top-edge-2) 

3; Find y-coord of starting point of stripe. Don’t go 

$3; past tha end of the triangle. 

for start-y from top-y by *stripe-distance* above last-y 
3; Find coords of ending point of the stripe, decrementing 
3; by HALF the horizontal distance between stripes 

for end-x downfrom (+ start-x top-edge-4) by half-distance 
for end-y downfrom (- top-y top-edge-4) by half-distance 
3; Find number of lines that make up the stripe 

for nlines = (compute-nlines (- xoff (- top-y start-~y))) 
3; Draw a stripe 

do (draw-big-arrow-shaft-lines-right 

niines start-x start-y end-x end-y last-y))) 


(defun draw-big-arrow-shaft-lines-right 
(nlines start-x start-y end-x end-y last-y) 
3; Set up two counters -- we need to draw two lines at once 
{loop for i from 0 
for i2 from 0 by 2 
33 Find y-coord of ending point of line 
for stop-y = (- end-y i) 
3; Don’t exceed number of lines in the stripe 
while (< i2 nlines) 
3; Don’t go past the bottom of the triangle 
while (< last-y stop-y) 
;; Draw a line 
do (send *dest*® *:show-lines start-x (- start-y i2) 
(- end-x i) stop-y) 
;; Draw a second line. The two lines are a refinement 
3; to stagger the endpoints of the lines so the diagonal 
3; edge looks neat. 
(send *dest*® °:show-lines start-x (- start-y i2 1) 
(- end-x i 1) stop-y))) 
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(defun stripe-arrow-shaft () 

3; Set up a counter for depth. Don’t exceed maximum 

3; recursion level. 

(loop for shaft-depth from *depth*® below *max-depth* 
3; Calculate fracticns of new top edge 
for top-edge-2 = *top-edge-2* then (// top-edge-2 2) 
for top-edge-4 = (// top-edge-2 2) 
3; Find coords of top lteft point of triangle 
for left-x = *p2x* then (- left-x top-edge-4) 
for top-y = *p2y* then (- top-y top-edge-2 top-edge-4) 
3; Find coords of bottom right point of triangle 
for right-x = (+ left-x top-edge-2) 
for bottom-y = (- top-y top-edge-2) 
33; Find x-coord of projection of first stripe onto top edge 
for xoff = (- *p0x® *top-edge*) 
then (- xoff top-edge-2 top-edge-2) 
33; Stripe the triangle 
do (draw-arrow-shaft-stripes 

| left-x top-y right-x bottom-y xoff))) 


(defun draw-arrow-shaft-stripes 
| (left-x top-y right-x bottom-y xoff) 
3; Find y-coord of starting point of stripe. Don’t go 
;; below the bottom of the triangle. 
(loop for start-y from top-y by *stripe-distance* above bottom-y 
3; Find x-coord of ending point of the stripa 
for end-x downfrom right-x by *stripe-d* 
3; Find number of lines in the stripe 
for nlines = (compute-niines (- xoff (- right-x end-x))) 
3; Draw a stripe 
do (draw-arrow-shaft-ilines 
| nlines left-x start-y end-x bottom-y))) 


(defun draw-arrow-shaft-lines 
(nlines left-x start-y end-x bottom-y) 
3; Set up a counter. Don’t exceed number of lines in the stripe. 
(loop for i from 0 below nlines 
33; Find x-coord of ending point of the line 
for last-x = (- end-x i) 
3; Don’t go past the left edge of the triangle 
while (< left-x last-x) 
3; Draw a line 
do (send *dest* °:show-lines left-x (- start-y i) 
last-x bottom-y))) 


Figure 3 (page 48) shows the output of the program with stripes of varying spacing and 
thickness. , 


At this stage in developing the program we define new functions, constants, and variables. But 
most of the work consists of changing existing code. Often you need to make similar changes 
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Figure 3. Program output with stripes of varying spacing and density. 
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to several functions: you add an argument or replace sending one message by a loop that sends 
several. In this case we are refining a new program, but when maintaining existing code you 
must also make selective or global changes. The most helpful Lisp Machine facilities are those 
for finding out about existing code (section 2.6, page 28) and for editing code (section 2.8, 


page 49). 


2.8 Editing Code 


The features we discussed in sections 2.2 (page 7) and 2.4 (page 19) are useful mainly in 
composing new code. The features we described in section 2.6 (page 28) are helpful in both 
writing and editing code. In this section we discuss features that are likely to be most useful in 
editing existing code. 


2.8.1 Identifying Changed Code 


Two pairs of List and Edit commands find or edit changed definitions in 
buffers or files. By default, the commands find changes made since the file 
was read; use numeric arguments to find definitions that have changed since 
they were last compiled or saved. 


Example 

After defining the routine that calculates the number of lines that compose 
each stripe, we changed many functions to call that routine and draw the 
appropriate number of lines. We want to look over the changes before 
recompiling the edited definitions. We use Edit Changed Definitions Of 
Buffer (m-X). | 


Reference 
List Changed Definitions Of Buffer (m-%) 
3 Lists definitions in the buffer that 
have changed since the file was read. 
Press c-. to edit the definitions 
listed. | 


Edit Changed Definitions Of Buffer (m-x) 
Prepares for editing definitions in the 
buffer that have changed. Press c-. 
to edit subsequent definitions. 


List Changed Definitions (m-%) Lists definitions in any buffer that 
have changed since the files were 
read. Press c-. to edit the 
definitions listed. 


Edit Changed Definitions (t#-X) Prepares for editing definitions in any 
buffer that have changed. Press c-. 
to edit subsequent definitions. 


Print Modifications (m-X) Displays lines in the current buffer 
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that have changed since the file was 


read. 

Source Compare (m-%) Compares two buffers or files, listing 
differences. 

Source Compare Merge (m-X) Compares two buffers or files and 


merges differences into a buffer. 


2.8.2 Searching and Replacing 


Many of the facilities discussed in section 2.6 (page 28), particularly the 
series of List and Edit commands, are useful for displaying and moving to 
code you wish to edit. The commands we discuss here find and replace 
strings. Tags tables offer a convenient means of making global changes to 
programs stored in more than one file. Use Select All Buffers As Tag 
Table (m-X) to create a tags table for all buffers read in. Use Select System 
As Tag Table (m-X) to create a tags table for all files in a system. (For 
information on systems, see the Lisp Machine Manual, chapter 24, page 406.) 


Example 
We have defined *stripe-d*, and we want to replace some occurrences of 
the constant *stripe-distance* by the variable *stripe-d*. We use Query 


- Replace (m-2%) to find each occurrence of *stripe-distance*. By pressing 


SPACE, we replace *stripe-distance* by *stripe-d* in functions like 
stripe-arrowhead. By pressing RUBOUT, we leave *stripe-distance* in place 
in functions like draw-big-arrow-shaft-stripes-left. 


Reference 

List Matching Lines (m-) Displays the lines (following point) in 
the current buffer that contain a 
string. 


Incremental Search (c-S) Prompts for a string and moves 
forward to its first occurrence in the 
buffer. Press c-S to repeat the 
search with the same string. Press 
c-R to search backward with the 
same string. After you invoke the 
command, if c-S is the first character 
you type (instead of a string), uses 
the string specified in the previous 
search. 


Reverse Search (c-R) Prompts for a string and moves 
backward to its last occurrence in the 
buffer. Press c-R to repeat the 
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Tags Search (m-%) 


Replace (c-2) 


Query Replace (m-2) 


Tags Query Replace (m—-%) 


jl 


search with the same string. Press 
c-S to search forward with the same 
string. After you invoke the 
command, if c-R is the first character 
you type (instead of a string), uses 
the string specified in the previous 
search. 


Searches for a string in all files listed 
in a tags table. 


In the buffer, replaces all occurrences 
(following point) of one string by 
another. 


In the buffer, replaces occurrences 
(following point) of one string by 
another, querying before each 
replacement. Press HELP for possible 
responses. — 


In files listed in a tags table, replaces 
occurrences of one string by another, 
querying before each replacement. 


Select All Buffers As Tag Table (m-x) 


Select System As Tag Table (m-X) 


2.8.3 Moving Text 
2.8.3.1 Moving through Text 


Creates a tags table for all buffers in 
Zmacs. 


Creates a tags table for files in a 
system defined by defsystem. 


To move short distances through text, you can use the Zmacs commands for 
moving by lines, sentences, paragraphs, Lisp forms, and screens, or you can 
click left to move point to the mouse cursor. To move longer distances, you 
can move to the beginning or end of the buffer or use the scroll bar. To go 
to another buffer, use Select Buffer (c-X B). To switch back and forth 
between two buffers, use Select Previous Buffer (c-m-l.). 


Suppose you want to record a location of point so that you can return to 
that location later. Two techniques are particularly useful: 


e Store the location of point in a register. Use Save Position (c-X S) to store 
point in a register. Use Jump to Saved Position (c-X J) to return to that 


location. 


e Use m-SPACE to push the location of point onto the mark stack. Later, you 
can use c-m-SPACE to exchange point and the top of the mark stack. c-U 
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c-SPACE pops the mark stack; repeated execution moves to previous marks. 
Note: Some Zmacs commands other than c-SPACE push point onto the 


“mark stack. When point is pushed onto the mark stack, the notification 


"Point pushed" appears below the mode line. 


Reference 

Select Buffer (c-% B) Moves to another buffer, reading the 
buffer name from the minibuffer. 
With a numeric argument, creates a 
new buffer. 

Select Previous Buffer (c-m-L) Moves to the previously selected 
buffer. 

Save Position (c-X $) Stores the position of point in a 
register. Prompts for a register name. 

Jump To Saved Position (c-x J) Moves point to a position stored in a 
register. Prompts for a register name. 

Set Pop Mark (c-SPACE) With no argument, sets the mark at 


point and pushes point onto the mark 
stack. With an argument of c-U, 
pops the mark stack. 


Push Pop Point Explicit (n-SPACE) With no argument, pushes point onto 
the mark stack without setting the 
mark. With an argument n, 
exchanges point with the nth position 
on the mark stack. 


Move To Previous Point (c-m-SPACE) Exchanges point and the top of the 
mark stack. 


Swap Point And Mark (e-X ¢-x) Exchanges point and mark. Activates 
the region between point and mark. 
Use Beep (c-G) to turn off the 
region. . 


2.8.3.2 Killing and Yanking 


When you need to repeat text, you usually want to copy it rather than type 
it anew. The most common facilities for copying text are the commands for 
killing and yanking. Commands that kill more than one character of text 
push the text onto the kill ring. c-Y yanks the last kill into the buffer. 
After a c-Y command, m-Y deletes the text just inserted, yanks the previous 
kill, and rotates the kill ring. 


Program Development Tools and Techniques 53 


Symbolics, Inc. 


Example 

In the function draw-big-arrow-shaft-lines-left, we send two :show-lines 
messages on each iteration. The purpose is to arrange the starting points of 
the lines along the diagonal edge so that they lie as closely as possible on a 
45-degree line. The second send expression is nearly identical to the first. 
Instead of typing a new expression, we copy and edit the first one. We 
follow these steps: 


. Position the cursor after the close parenthesis that ends the first send 


expression. 


(defun draw-big-arrow-shaft-lines-left 
(nlines start-x start~y end-x end-y last-x) 


« 


do (send *dest* °:show-lines first-x (- start-y 1) 
(- end-x i2) end-y) 


. Use c-m-RUBOUT to kill the send expression and push it onto the kill ring. 


(defun draw-big-arrow-shaft-lines-left 
(nlines start-x start-y end-x end-y last-x) 


do 


. Use c-¥ to restore the expression. 


(defun draw-big-arrow-shaft-lines-left 
(nlines start-x start-y end-x end-y last-x) 


do (send *dest* ’:show-lines first-x (- start-y i) 
(- end-x i2) end-y) 


4. Use LINE to move to the next line and indent. 
. Use c-¥ to insert a copy of the send expression. 


(defun draw-big-arrow-shaft-lines-left 
(nlines start-x start-y end-x end-y last-x) 


do (send *dest* ’:show-lines first-x (- start-y i) 
(- end-x 12) end-y) 

(send *dest*® *:show-lines first-x (- start-y i) 
(- end-x i2) end-y) 


54 Program Development Tools and Techniques 


6. Edit the second send expression. 


Symbolics, Inc. 


(defun draw-big-arrow-shaft-lines-left 
(nlines start-x start-y end-x end-y last-x) 


do (send *dest* °:show-lines first-x (- start-y i) 
(- end-x i2) end-y) 

(send *dest* *°:show-lines first-x (- start-y i 1) 
(- end-x i2 1) end-y))) 


Example 


Suppose we have an existing program in which we have already defined the 
function compute-nlines. We can copy the function in three ways: 


e Use c-m-K or c-m-RUBOUT to kill the definition. Use c-¥ to restore it. Go 
to the new buffer. Use c~¥ to insert a copy of the definition. 


e Use c-m-H to mark the definition. Use m-W to push it onto the kill ring. 
Go to the new buffer. Use c-¥ to insert a copy of the definition. 
e Click middle on the first or last parenthesis of the definition to mark the 


definition. Click double-middle to push it onto the kill ring. Move to the 
new buffer. Click double-middle to insert a copy of the definition. 


Reference 
Kill Sexp (c-m-K) 


Backward Kill Sexp (c-m-RUBOUT) 
Mark Definition (c~m-H) 
Save Region (m-W) 


Yank (c-¥) 


Yank Pop (m-Y) 


Kills forward one or more Lisp 
expressions. 


Kills backward one or more Lisp 
expressions. 


Puts point and mark around the 
current definition. 


Pushes the text of the region onto the 
kill ring without killing the text. 


Pops the last killed text from the kill 
ring, inserting the text into the buffer 
at point. With an argument 7, yanks 
the ath entry in the kill ring. Does 
not rotate the kill ring. 


After a c-Y command, deletes the 
text just inserted, yanks previously 
killed text from the kill ring, and 
rotates the kill ring. Repeated 
execution yanks previous kills and 
rotates the kill ring. 
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[Region (M2)] 


2.8.3.3 Using Registers 


IS 


When region is defined, pushes the 
text of region onto the kill ring 
without killing the text (like m-W). 
Repeated execution has the following 
effects: 


First repetition: kills the text of 
region, pushing the text onto the kill 
ring (like c-W) 

Second repetition: pops the text of 
region from the kill ring, inserting the 
text into the buffer at point (like 
c-Y) 

Third and subsequent repetitions: 
delete the text just inserted, yank 
previously killed text from the kill 
ring, and rotate the kill ring (like 
m-Y) 


If no region is defined, pops the last 
killed text from the kill ring, inserting 
the text into the buffer at point (like 
c-Y). Repeated execution deletes the 
text just inserted, yanks previously 
killed text from the kill ring, and 
rotates the kill ring (like m-Y). 


Using c-Y and m-Y to copy text can become tedious when you have to 


_ - rotate through a long kill ring to find the text you need. Another method, 


especially useful when you want to copy a piece of text more than once, is 
to save and restore the text using registers. 


Reference 
Put Register (c-X x) 


Open Get Register (c-X G) 


Copies contents of the region to a 
register. Prompts for a register name. 


Inserts contents of a register into the 
current buffer at point. Prompts for 
a register name. 


2.8.3.4 Copying Buffers and Files 


Use Insert File (m-X) to place the contents of an entire file in your buffer. 


You can copy the contents of a buffer in two ways: 
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e Use Insert Buffer (m-X), naming the buffer you want to copy. 


e Use c-X H to mark the buffer you want to copy. Use m-W to push its text 
onto the kill ring. Move to the new buffer. Use c-Y to insert a copy of 


the text. 


Reference 
Mark Whole (c-*% H) 


Insert Buffer (m-%) 


Insert File (m-%) 


2.8.4 Keyboard Macros 


Marks an entire buffer. 


Inserts contents of the specified 
buffer into the current buffer at 
point. 


Inserts contents of the specified file 
into the current buffer at point. 


Sometimes you need to perform a uniform sequence of commands on several 
pieces of text. You can save keystrokes by converting the sequence to a 
keyboard macro and installing it on a single key. If you anticipate using a 
macro often, you can write Lisp code to define it in an init file. If you 
frequently use particular extended commands, install them on single keys 


with Set Key (m-x). 


Reference 
Start Kbd Macro (c-x ¢) 


End Kbd Macro (e-X >) 


Call Last Kbd Macro (c-% E) 
Name Last Kbd Macro (m-X) 


Install Macro (m-X) 


Install Mouse Macro (m-%) 


Deinstall Macro (m-X) 


Set Key (m-%) 


Begins recording keystrokes as a 
keyboard macro. 


Stops recording keystrokes as a 
keyboard macro. 


Executes the last keyboard macro. 


Gives the last keyboard macro a 
name. 


Installs on a key the last keyboard 
macro or a named macro. 


Installs a keyboard macro on a mouse 
click (such as L2). When you click 
to call the macro, point moves to the 
position of the mouse cursor before 
the macro is executed. 


Deinstalls a keyboard macro from a 
key or a mouse Click. 


Installs an extended command on a 
single key. Use HELP C to look for 
unassigned keys. 
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2.8.5 Using Multiple Windows 
2.8.5.5 Multiple Buffers 


Sometimes when editing you move often between two buffers. You might 
want to see the two buffers at the same time rather than switch between 
them. A common use of multiple-window display is to edit source code 
while viewing compiler warnings (see section 4.1, page 71). 


Example 

We add a new :show-lines message to the program but forget what 
arguments the message takes. We want to display the source code for the 
message handler on the same screen as our program code. We use c-X 2 to 
create another window and move to it. We use Edit Methods (m-X) to find 
the source code for the method that handles :show-lines (see section 5.2.2, 
page 129). 


Example 

After finishing the program, we collect a file of bug reports from users. We 
want to use these reports in correcting our program code. We create two 
windows, one displaying the program code and the other the bug-report file. 
We edit the program code, using c-m-¥ to scroll the bug-report window as 
we correct each bug. 


Reference 

Split Screen (n-X) Pops up a menu of buffers and splits 
the screen to display the buffers you 
select. 

Two Windows (c-X 2) Creates a second window, with the 

current buffer on top and the 
previous buffer on the bottom. Puts 
the cursor in the bottom window. 

View Two Windows (c-x 3) Creates a second window, with the 

current buffer on top and the 

previous buffer on the bottom. Puts 
the cursor in the top window. 

Modified Two Windows (e-X 4) Creates a second window and visits a 
buffer, file, or tag there. Displays the 
current buffer in the top window. 

Other Window (c-X 0) Moves to the other of two windows. 

Scroll Other Window (c-m-¥) Scrolis the other of two windows. 


One Window (c-X 1) Returns to one-window display, 
x selecting the buffer the cursor is in. 
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2.8.5.6 Zmacs and Other Windows 


Use [Split Screen] or [Edit Screen] from a system menu to display an editor 
window on the screen with other kinds of windows. 


Example 

In testing new program functions, we want to have the current version of 
the figure on the same screen as the program code. We use [Split Screen] 
from a system menu to add a Lisp Listener to the screen. We move 
between windows by clicking left on the window to which we want to 
move. 


We evaluate (pkg-goto ’graphics) and then (do-arrow) in the Lisp 
Listener. We adjust the arguments to draw-arrow-graphic so that the 
arrow fits neatly into the Lisp Listener window. 


(defun do-arrow () 
(let ((*dest* (make-instance °’screen-arrow-output) )) 
(send terminal-io ’:clear-screen) 
(draw-arrow-graphic 640 1300 1850))) 


Figure 4 (page 59) shows the appearance of the screen with graphic output 
in a Lisp Listener and source code in a Zmacs buffer. 


To return to displaying only the Zmacs window, we use [Split Screen] with 
the existing Zmacs buffer as the only element. 


Reference 

{Split Screen / Lisp / Existing Window / Existing Zmacs Buffer / Do It] 
(from a system menu) 
Adds a Lisp Listener to a screen 
displaying an existing Zmacs buffer. 


[Split Screen / Existing Window / Existing Zmacs Buffer / Do It] (from a 
system menu) 
Resumes one-window display of an 
existing Zmacs buffer. 


2.8.5.7 Other Displays 


The window system allows you to use menus, choose-variable-values 
windows, and other multiple-window displays in executing programs. See 
Introduction to Using the Window System and Lisp Machine Choice Facilities 
for details. See chapter 5 (page 101) for examples of simple uses of 
windows, including choose-variable-values windows. 
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Lisp Listener 2 


Calculates the number of lines that conpose each stripe. 
Calls COMPUTE-DENS to calculate the proportion of distance 
between stripes to be filled, then multiplies by the actual 
distance between stripes. Makes sure that there is at least 
one line and that there aren’t too nany lines to leave sone 
white space. 
fun compute-nlines (x) 
Call COMPUTE-DENS and multiply result by *STRIPE-Ds 
t ((n) (fix (s *stripe-dt (compute-dens x))))) 
Supply at least one line 
1) 1) 
3; But leave some white space between lines 
((2 nl (- tstripe-dt 1)) (- tstripe-ds 2)) 
(t ni)))) 


mee we we we we os 


Calculates proportion of distance filled in between each stripe. 
The argument is the x-coordinate of the projection of the current 
stripe onto the Tine formed by the top edge. Determines where the 
projection of the current stripe is on this line in relation to the 
distance from first to last stripes in the arrow. Multiplies this 
fraction by the difference between densities of first and last 
stripes. Finally, adds the density of the first stripe. 
fun compute-dens (x) 
+ diz (s (- sd2s tdis) 

(77 (- x 8pOxt) (float (- x28 ep@x%)))))) 


NTs we ws we ws we we 


2MACS (LISP) poodex.1 /dess/doc/workstyles/ VIXEN: .% More above and below 


:Move point, L2:Move to point, M:Mark Ciinge: Hespevern i Licyank, R:Menu, R2:Systen menu. 
@8717/783 18:86:25 ron GRAPHICS: Ty 


Figure 4. Using multiple windows to test the program while viewing the source code. 
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3. Compiling and Evaluating Lisp 


When should you compile code, and when evaluate it? 


The main job of the compiler is to convert interpreted functions into compiled functions. An 
interpreted function is a list whose first element is lambda, named-lambda, subst, or 
named-subst. These functions are executed by the Lisp evaluator. The most common 
interpreted functions you define are named-lambdas. When you load a source file that 
contains defun forms or when you otherwise evaluate these forms, you create named-lambda 
functions and define the function specs named in the forms to be those functions. 


Compiled functions are Lisp objects that contain programs in the Lisp Machine instruction set 
(the machine language). They are executed directly by the microcode. Compiling an 
interpreted function (by calling the compiler on a function spec) converts it into a compiled 
function and changes the definition of the function spec to be that compiled function. 


You seldom compile functions directly. Instead, you compile either regions of Zmacs buffers or 
source files. 


e Compiling a region of a Zmacs buffer (or the whole buffer) causes the 
compiler to process the forms in the region, one by one. This processing has 
side effects on the Lisp environment. We summarize the compiler’s actions 
in section 3.1.1 (page 62). 

e Compiling a source file translates it into a binary file. With some 
exceptions, this processing does not have side effects on the Lisp 
environment at compile time. When you load a compiled file that defines 
functions, you create compiled rather than interpreted functions and define 
function specs to be those compiled functions. In other respects, loading a 
compiled file has essentially the same effects as loading a source file 
(evaluating the forms in the file). We discuss compiling files in section 3.1.2 


(page 65). 


Most Symbolics programmers compile all their program code. The compiler checks extensively 
for errors and issues warnings that help detect bugs like typographical errors, unbound symbols, 
and faulty Lisp syntax. Compiled code runs faster and takes up less storage than interpreted 
code. You can compile code in portions and decide at compile time whether or not to save the 
compiler output in a binary file. 


The most common use for interpreted functions is stepping through their execution. You 
cannot step through the execution of a compiled function. If a function is compiled, you can 
read its definition into a Zmacs buffer, evaluate the definition, and then step shrough ao 
function call. 


In addition to evaluating definitions to create interpreted functions, you might need to evaluate 
forms to test a program or find information about a Lisp object. (Unless you are using the 
Stepper, functions that you call during these evaluations are usually compiled.) You can 
evaluate a form in a Lisp Listener, a breakpoint loop, or the minibuffer. 


See the Lisp Machine Manual, chapter 10, page 136, for more information on functions. 
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3.1 Compiling Lisp Code 


You can use Zmacs commands to compile code in a file or Zmacs buffer. Most Symbolics 
programmers compile code as soon as they have written enough to test. This practice lets them 
correct errors quickly and produce simple working versions of programs before adding more 
complex operations. A common command for incremental compiling from a Zmacs buffer is 
Compile Region (c-sh-C). If no region is defined, this command compiles the current 
definition. 


In addition to compiling definitions as they write them, Symbolics programmers consider it 
good practice to recompile a function soon after effecting a change. Because recompiling a 
series of functions or an entire program can be time-consuming, it is easier and faster to make 
changes and then use a single command to recompile only the changed functions. Using 
Compile Changed Definitions Of Buffer (m-sh-C) or Compile Changed Definitions (m-%) is 
easier in this case than recompiling each function separately or recompiling the entire buffer. 


The order in which you compile definitions can be important. For example, suppose you have 
a function that binds a variable you want to be treated as special. If you compile the function 
definition before compiling the variable declaration, the compiler treats the variable as local 
and generates incorrect output. For this reason you should usually put defvar and defconst 
forms at the beginning of a file or into a separate file to be compiled and loaded before 
function definitions. 


When editing a program, it is a good idea to load the entire program before you start work on 
it. When you compile new definitions or recompile edited ones, the compiler will have access 
to variable declarations, macros, functions, and other information. You will also be able to use 
Zmacs commands and Lisp functions for finding information about other parts of the program 
(see section 2.6, page 28). 


Sometimes when you compile a file, write large sections of code at once, or make many changes 
to a large program, compiling the code produces many warning messages. Chapter 4 (page 71) 
describes how Edit Compiler Warnings (m-X) lets you use the compiler warnings as a reference 
source for debugging. . 


See the Lisp Machine Manual, chapter 16, page 197, for more information on the compiler. 


3.1.1 Compiling Code in a Zmacs Buffer 
Compiling a top-level form in a Zmacs buffer — using a command like 
Compile Region (c-sh-C) or Compile Buffer (m-X) — has side effects on 
the Lisp environment. Following is a summary of the compiler’s actions: 


Form Action 


Macro form If the form is a list whose first element is a 
macro, the compiler expands the form and 
processes this expanded form instead of the 
original. 


Function definition If the form is a list whose first element is defun, 
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the compiler constructs a lambda-expression from 
the definition, converts the lambda-expression into 
a compiled function, and defines the function spec 
named in the definition to be that compiled 
function. 


Macro definition If the form is a list whose first element is macro, 
the compiler constructs a lambda-expression as the 
macro’s expander function, converts the lambda- 
expression into a compiled function, and defines 
the function spec named in the definition to be 
the macro. A defmacro form expands into this 
kind of form. 


Special case Some forms, like eval-when, declare, and 
progn ’compile forms, have special meaning for 
the compiler. It handles each of these in a 
different way. (See the Lisp Machine Manual, 
chapter 16, page 197, for details.) 


Atom, comment form _ The form is ignored. 


Other The form is evaluated. 


Example 
We have written some initial code for the controlling function of the 
calculation module: 


(defvar *top-edge* nil 
“Length of the top edge of the arrow") 


(defvar *p0x*® nil 
*X-coordinate of point 0") 


(defvar *p0y* nil 
"Y-coordinate of point 0") 


(defun draw-arrow-graphic (*top-edge® *p0x *p0y*) 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4))) 
(draw-big-arrow) ) ) 


Because we have no other code in the buffer, we can compile these 
definitions using Compile Buffer (m-%). If we had more code in the buffer, 
we could compile these definitions by setting the mark at one end and point 
at the other and using Compile Region (c-sh-C). 


The compiler displays the following warnings: 
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For Function DRAW-ARROW-GRAPHIC 
The variable *TOP-EDGE-4* was never used. 
The variable *TOP-EDGE-2* was never used. 
The variable *POX was never used. 


The following functions were referenced but don’t seem defined: 
DRAW-BIG-ARROW referenced by DRAW-ARROW-GRAPHIC 


The first set of warnings indicates that the compiler is treating 
*top-edge-2*, *top-edge-4*, and *pOx as local variables. We neglected to 
declare *top-edge-2* and *top-edge-4* special with defvar; *pOx is of 
course a misspelling. The lack of a definition for draw-big-arrow is not 
surprising; we have yet to write that definition. 


‘We add the two defvars and correct the spelling of *pOx*. We compile the 
changes using Compile Changed Definitions Of Buffer (m-sh-C). The 
_ compiler now displays only one warning: 


The following functions were referenced but don’t seem defined: 
DRAW-BIG-ARROW referenced by DRAW-ARROW-GRAPHIC 


We continue writing the program by defining draw-big-arrow. 


Reference 
Compile Region (e-sh-C) Compiles the region. If no region is 
. _ marked, compiles the current 
definition. 


[Zmacs Window / Compile Region] Compiles the region. If no region is 
marked, compiles the current 
definition. 


Compile Changed Definitions Of Buffer (n-sh-C) 
Compiles all the definitions in the 
current Zmacs buffer that have 
changed since the definitions were last 
compiled. 


Compile Changed Definitions (m-X) Compiles all the definitions in any 
Zmacs buffer that have changed since 
the definitions were last compiled. 


Compile Buffer (m—-%) Compiles the current Zmacs buffer. 


Compile (m-%) [Zmmacs Window (R)] Pops up a menu of options for 
compiling code in the current context. 
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3.1.2 Compiling and Loading a File 
Compiling a file, using Compile File (m-X) or compiler:compile-file, saves 
the compiler output in a binary file of canonical type :bin. For the most 
part, compiling a file does not have side effects on the Lisp environment. 
The basic difference between compiling a source file and compiling the same 
forms in a buffer is this: When you compile a file, most function specs are 
not defined and most forms (except those within eval-when (compile) 
forms) are not evaluated at compile time. Instead, the compiler puts 
instructions into the binary file that cause these things to happen at load 
time. You can load a source or binary file into the Lisp environment by 
using Load File (m-X) or load. You can compile a file and then load the 
resulting binary file by using compiler:compile-file-load. 


Example . 

In a previous session, we wrote the output routines for the program, saved 
them in a file, and compiled that file. Now we are writing the first 
calculation routines, and we want to test them. We need to load the file 
that contains the compiled code for the output routines. We use Load File 
(m-%). 


Suppose our two files are in the directory >Symbolics>examples> on Lisp 
Machine acme-blue. The file containing the output routines is arrow-out. 
The current Zmacs buffer, and the file containing the calculation module, is 
arrow-calc. When we type m-X load file (or m-X lo f, using completion), 
Zmacs prompts for a file name: _ 


Load File: (Default is ACME-BLUE:>Symbolics>examples>arrow-calc) © 


We type arrow-out, without a file type. The latest version of 
arrow-out.bin is loaded. If no compiled version exists or if the latest 
compiled file is older than the latest source file, Zmacs offers to compile the 
source file and then load the compiled version. 


Reference | | 

Compile File (m-%) Prompts for the name of a file and 
compiles that file, placing the 
compiled code in a file of canonical 


type :bin. 


(compiler:compile-file fi/e-name) Compiles a file, placing the compiled 
code in a file of canonical type :bin. 


Load File (mx) Prompts for a file name, taking the 
: default from the current buffer. 
Offers to save the buffer if it has 
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changed since the file was last read or 
saved. Offers to compile the source 
file if no compiled version exists or if 
the source file was created after the 
latest compiled version. If you specify 
a file type, loads the latest version of 
the file of that type. If you don’t 
specify a file type, loads the latest 
version of the binary file (even if 
older than the latest source file); if no 
binary file exists, loads the latest 
source file. 


Loads a file into the Lisp 
environment. If you specify a file 
type, loads the latest version of the 
file of that type. If you don’t specify 
a file type, loads the latest version of 
the binary file (even if older than the 
latest source file); if no binary file 
exists, loads the latest source file. 


(compiler:compile-file-load file-name) 


3.2 Evaluating Lisp Code 


3.2.1 Evaluation and the Editor 


Compiles a file, placing the compiled 
code in a file of canonical type :bin. 
Loads the resulting binary file. 


The most common reason for evaluating definitions in a Zmacs buffer is to 
step through the execution of the functions they define. Sometimes in 
debugging you want to proceed step by step through a function call, using 
step or the :step option to trace (see section 4.4.2, page 86). You can do 
this only with interpreted functions. If a function is compiled, you can use 
Edit Definition (m-.) to read its definition into a Zmacs buffer. You can 
then evaluate the definition using Evaluate Region (e-sh-E). When you 
have finished stepping, you can recompile the definition. 


The evaluation of Lisp forms in the editing buffer or the minibuffer 
normally displays the returned values in the echo area (beneath the mode 
line near the bottom of the screen). Any output to standard-output during 
the evaluation appears in the editor typeout window. ‘Two commands, 
Evaluate Into Buffer (m-%) and Evaluate And Replace Into Buffer (m-%), 
print the returned values in the Zmacs buffer at point. With a numeric 

_ argument, these commands also insert any typeout from the evaluation into 


the Zmacs buffer. 
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Often while editing you need to evaluate forms other than definitions in a 
buffer. You need to call a function to test your program, or you need to 
call a function like describe to find information about a Lisp object. (Of 
course, these functions need not be interpreted.) You can type forms to be 
evaluated in three ways: 


Use m-ESCAPE to evaluate a form in the minibuffer. 

Use SUSPEND to enter a Lisp breakpoint loop. You type forms that are 
read in the buffer’s package and evaluated. Use RESUME to return to the 
editor. 

Use SELECT L or [Lisp] from a system menu to select a Lisp Listener and 
evaluate forms there. Use SELECT E or [Edit] from a system menu to 
return to the editor. 


Example 

We have found a bug in the program and suspect that it lies in the function 
do-arrows. We want to step through a call to that function, but it is 
compiled. We use Edit Definition (i—-.) to find the definition of do-arrows 
and Evaluate Region (c-sh-E) to evaluate the definition. We then step 
through a function call (see section 4.4.2, page 86). 


Example 

We have written and compiled the output routines and the initial code for 
the calculation module. We want to test the program as written so far. 
The top-level function to call is do-arrow. We can test the program in 
three ways: 


Press m-ESCAPE and evaluate (do-arrow). The graphic output appears in a 
typeout window. We press SPACE to restore the editing buffer to the 
screen. 


Press SUSPEND to enter a Lisp breakpoint loop and evaluate (do-arrow) 
there. We press RESUME to return to the editor. 


Press SELECT L to select a Lisp Listener. If the current package is not 
graphics, we first evaluate (pkg-goto ’graphics) and then (do-arrow). We 
press SELECT E to return to the editor. 


Example 

We want to be sure that new function names do not conflict with other 
symbol names in the graphics package. Most of our function names 
contain the string "arrow". We want to find the symbol names that contain 
that string. We use m-ESCAPE, SUSPEND, or SELECT L and evaluate: 


(apropos "arrow" ’graphics) 
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Reference 

Evaluate Region (c~sh-E) Evaluates the region. If no region is 
marked, evaluates the current 
definition. 


Evaluate Changed Definitions Of Buffer (m-sh-E) 
Evaluates all the definitions in the 
current Zmacs buffer that have 
changed since the definitions were last 
evaluated. 


Evaluate Changed Definitions (m-X) Evaluates all the definitions in any 
Zmacs buffer that have changed since 
the definitions were last evaluated. 


Evaluate Buffer (m-X) Evaluates the current Zmacs buffer. 


Evaluate Into Buffer (m-) Prompts for a Lisp form to evaluate 
and prints the returned values in the 
Zmacs buffer at point. 


Evaluate And Replace Into Buffer (m—-) 
Evaluates the Lisp form following 
point and replaces it with the printed 
representation of the values it returns. 


Evaluate Minibuffer (m-ESCAPE) Prompts for a Lisp form to evaluate 
in the minibuffer and displays the 
returned values in the echo area. 


Evaluate (m-%) [Zmacs Window (R)] Pops up a menu of options for 
evaluating code in the current 
context. 


SUSPEND Enters a Lisp breakpoint loop, where 
you can evaluate forms. The current 
package in the breakpoint loop is the 
same as in the previous context. Use 
RESUME to return to the previous 
context. 


3.2.2 Lisp Input Editing 

When typing to a Lisp Listener you can use many editing commands to 

_ modify a form before you evaluate it. You often repeat the same function 
calls or variations of similar function calls when testing code. Instead of 
retyping these forms, you can use the Lisp input editor’s ring of input 
entries to retrieve them within the same Lisp Listener. When you yank a 
previous form, the Lisp input editor places the cursor at the end of the form 
but omits the final close parenthesis or carriage return. You can then edit 
the form before typing the final delimiter to evaluate it. 
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Example 

We execute our program by calling the function do-arrow. We evaluate 
(do-arrow) once and would like to evaluate it again within the same Lisp 
Listener. We press e~-C to yank the last form we typed. If that is not 
(do-arrow), we press m-C until (do-arrow appears, without the close 
parenthesis. We type a close parenthesis to begin the evaluation. 


Reference 

c-C Yanks the last form typed to the Lisp 
Listener. Excludes the final delimiter, 

: allowing you to edit the form before 

evaluating it. With an argument a, 
yanks the nth form in the input ring. 
(This command is not available in 
Zmacs.) 


m—-C After a c-C command, deletes the 
form just inserted, yanks the previous 
form from the input ring, and rotates 
the input ring. Repeated execution 
yanks previous forms and rotates the 
input ring. (This command is not 
available in Zmacs.) . 
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4. Debugging Lisp Programs 


The Lisp Machine offers a variety of tools for debugging Lisp programs. The kind of 
debugging aid you use depends on the application of the program. Bugs might be more obvious 
in a graphics program than in a minor modification of some internal system function. 

Problems with a graphics programs are sometimes evident from the program’s output. On the 
other hand, programs with a complex window system application might have bugs that are 
difficult to identify. 


Debugging aids are more appropriate for some kinds of bugs than for others. You commonly 
encounter three sorts of problems with a program: 


e The program does not compile correctly. You can use the compiler 
warnings database to edit code before recompiling. 

e The program compiles, but running it signals an error. Usually errors 
invoke the Debugger, where you can examine stack frames, return values, 
disassemble code, call the editor, and perform other tasks. 

e The program runs but does not behave as it should. You can use many 
techniques for finding the problem, including commenting out sections of 
code, tracing, stepping, setting breakpoints, disassembling, and inspecting. 
Often the most effective method is simply studying the source code. 


4.1 The Compiler Warnings Database 


The compiler sometimes produces many warning messages. The compiler maintains a database 
of these messages, organized by file. Each time you compile or recompile code, the compiler 
adds or removes warnings from the database, so that the database reflects the state of your 
program as of the last time you compiled it. 


If you want to save warnings in a file, you can use Compiler Warnings (m-X%) to put them in a 
buffer and then write them to a file. When you make a system using make-system, you can 
use the :batch option to save compiler warnings in a file (see the Lisp Machine Manual, 
section 24.3, page 411). Use Load Compiler Warnings (m-X) to load compiler warnings into 
the database from a file. 


If compiler warnings exist in the database, Edit Compiler Warnings (m—X) lets you edit source 
code while consulting the corresponding warnings. The command splits the screen, with 
compiler warnings in one window and the source code to which the warnings apply in the 
other. As you finish editing each section of code, you press c-.. This displays the next 
warning in one window and the source code to which the next warning applies in the other 
window. When you reach the last compiler warning, pressing c-. returns the screen to its 
previous configuration. 


Example 

In section 3.1.1 (page 62), we discussed compiling the initial code for the 
calculation module of the sample program. Figure 5 (page 72) shows the 
result of using Edit Compiler Warnings (m-X) after compiling the buffer 
with the initial code. The compiler warnings are in the upper window and 
the source code in the lower window. 
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Warnings for file VIXEN: /dess/doc/worksty!les/pcodex.2 


@ For Function DRAW-ARROW-GRAPHIC 

The variable *tTOP-EDGE-4*% was never used. 

The variable sTOP-EDGE-2% was never used. 

The variable *P@X was never used. 
DRAW-BIG-ARROW was referenced but not defined. 


tConpi ler-Warnings~-1% 
defun draw-arrow-graphic (ttop-edget *tp@x *pGys 
(let ((top-edge-2% (7/ ttop-edget 2)) 
(ttop-edge-4% (7/7 ttop-edget 4))) 
(draw-big-arrow) )) 


pcodex. | /dess/doc/workstyles/ VIXEN: 
ZMACS (LISP) pcodex.! /dess/doc/workstyles/ VIXEN: * 
Contro!-. is now Edit warnings for next function. 
1 more definition as well 
Point pushed 


:Move point, L2:Move to point, rk t ine M2:Save/KilivYank, R:Menu, R2:Systenm menu. 
08728083 16:49:52 ron GRAPHICS: Tyi 


Figure 5. Edit Compiler Warnings (m-X) splits the screen. The upper window contains 
compiler warnings. The lower window contains the source code. 
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Reference 

Edit Compiler Warnings (m-%) Prepares to edit all source code that 
has produced compiler warnings. 
Lists each file whose code produced 
warnings and asks whether you want 
to edit that file. Splits the screen, 
with compiler warnings in the upper 
window and source code that 
produced those warnings in the lower 
window. Use c-. to display 
subsequent warnings and edit the 
applicable code. 


Compiler Warnings (m-) Puts compiler warning messages into a 
buffer and selects that buffer. 


Load Compiler Warnings (m-X) Loads a file containing compiler 
warning messages into the compiler 
warnings database. 


4.2 The Debugger 


Some errors during execution automatically invoke the Lisp Machine’s Debugger. You can 
enter the Debugger at other times by pressing c-m-SUSPEND. You can also enter the Debugger 
from within a program by inserting a call to dbg (with no arguments) into the code and 
recompiling. You can force a process into the Debugger by calling dbg with an argument of 
process. (See section 4.5, page 89.) 


The Debugger is useful for examining stack frames. With Debugger commands, you can see 
the arguments for the current stack frame, disassemble its code, return a value from it, go up 
and down the stack, and invoke the editor to edit function definitions. A common Debugger 
sequence is to disassemble code for the current frame, call the editor to edit and recompile the 
function, and test the changed function. 


A window-oriented version of the Debugger is the Display Debugger. Invoke it from within 
the Debugger by pressing c-m-W. 


Example 

We use the variable *x2* in computing the thickness of each stripe. *x2* is 
the x-coordinate of the projection of the last stripe in each arrow onto the 
top edge. We must bind it for each arrow to the difference between the 
value of *pOx* and twice the value of *top-edge*. 


Suppose that we forget to bind *x2* for the big arrow in the function 
draw-big-arrow. The initial value of *x2* is nil. In the function 
compute-dens, we subtract *pOx* from *x2*. Because the value of *x2* is 
not a number, we generate an error when we first call the function. The 
error invokes the Debugger with the name of the function in which the. 
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error occurred, the value of the function’s arguments, and the following 
error message: 


>>Trap: The first argument given to SYS:--INTERNAL, NIL, was not a number. 


The Debugger also displays a listing of proceed types, special commands, and 
restart handlers, along with their key bindings (see Signalling and Handling 
Conditions, section 10.5, page 41). We can use one of these options, or we 
can use other Debugger commands to examine or manipulate the stack. 

, Let’s use c-m-W to invoke the Display Debugger. 


Figure 6 (page 76) shows the Display Debugger frame as it looks when we 
invoke it. The top window, an inspect pane, shows disassembled code for 
compute-dens with an arrow at the instruction that produced the error. 
The next window is an inspect history pane. The two windows side by side 
show the function’s arguments and local variables and their values. The 
next window is a backtrace of the stack with an arrow at the frame that 
produced the error. The next window is a mouse-sensitive listing of options 
for proceeding or restarting. Next is a command menu. The bottom 
window is a Lisp Listener with the error message displayed. 


The disassembled code for compute-dens shows that the first argument to 
the subtraction that caused the error was the value of *x2*. We can 
inspect *x2* simply by clicking on its printed representation in the 
disassembled code. Figure 7 (page 77) shows the Display Debugger after we 
inspect *x2*. The value of *x2* is nil. We could have confirmed this by 
evaluating *x2* in the Lisp Listener pane. 


Now, if we remember what the value of *x2* is supposed to be, we can set 
*x2* to that value by typing to the Lisp Listener pane: 


(setq *x2* (- *p0x*® *top-edge* *top-edge*) ) 


We can then click on [Retry] to reinvoke the stack frame and continue the 
program. 


If we forget the value of *x2*, we might want to look at the source code. 
We can invoke the editor by clicking on [Edit] and then on the name of the 
function we want to edit. Inside the editor, we can change and recompile 
code. We can edit draw-big-arrow to bind *x2* and then recompile that 
function. If we entered the Debugger from the editor, we cannot return to 
the Debugger, but we can run the program again. Otherwise, we can return 
to the Display Debugger by pressing c-2. We can then set the value of 
*x2* and reinvoke the frame. 


In the Debugger, c~HELP displays information on Debugger commands. Following are some of 
the most useful commands: 
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Reference 

c-A Shows arguments for the current stack frame. 

c-E Calls the editor to edit the function from the current 
frame. 

e-L Clears the screen and redisplays the original error 
message. 

c-N Goes down the stack by one frame. 

c~-P Goes up the stack by one frame. 

e-R ~ Returns a value from the current frame. 

m-B Shows a backtrace of function names with arguments. 

m—L Shows local variables and disassembled code for the 
current frame. 

c-m-R Reinvokes the current frame. 

e-m-H Invokes the Display Debugger. 


4.3 Commenting Out Code 


Sometimes a program runs but behaves in an unexpected way. In looking for the source of the 
problem, you might want to execute some portions of the program and disable others. An easy 
way to disable code without destroying it is to make a comment of it. You can comment out 
code by preceding it with a semicolon or surrounding it with #| and |#. 


Example 

We have outlined the large arrow and the largest of the small arrows. We 
try to outline the rest of the small arrows by adding two recursive function 
calls to do-arrows: 
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COMPUTE-~-DENS 
3 PUSH-INDIRECT Dis 

BUILTIN --INTERNAL STACK 
PUSH-LOCAL FP|@ 3X 
PUSH-INDIRECT *PQxXs 
BUILTIN --INTERNAL STACK 
PUSH-INDIRECT EHZEy 
PUSH-INDIRECT *PGX 
BUILTIN --INTERNAL STACK 
BUILTIN FLOAT STACK 
BUILTIN 7-INTERNAL STACK 


&<Stack-Frame COMPUTE-DENS PC=12> 


Args: 
Arg @ (X): 1880 


(DO-ARROW) 

(DRAW-ARROW-GRAPHIC 1288 188@ 1880) 
( DRAW-BIG-ARROW) 

(STRIPE-RRROWHEAD) 

(COMPUTE-NLINES 18@@) 
*(COMPUTE-DENS 1888) 


More delow 


Return to normal debugger, staying in error context. 
Supply replacenent argument 

Return a value from the --INTERNAL Instruction 
Retry the --INTERNAL instruction 

Lisp Top Level in Lisp Listener 1 


set. arg 
Arglist i Search 
>>Trap: The first argument given to SYS:--INTERNAL, NIL, was not a number. 


pointing at the value 


hoose a value by i Sane art object into error handler. 
@8/28/83 17:01:23 ron GRAPHICS: T 


Figure 6. The Display Debugger: inspecting the stack frame containing a call to 
compute-dens. 
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Top of odject 


is unbound 
Property !ist: (DOCUMENTATION °...° SPECIAL &<UNIX-PATHNAME “VIXEN: //dess//workstyles¢ 
Package: #<Package GRAPHICS 36635277> 


Bottom of object 


#<Stack-Frane COMPUTE-DENS PC=12> 
22s 


Args 
Ars @ (x): 1600 


More above 
(DO-RRROW) 
(DRAW-ARROW-GRAPHIC 1286 1888 1886) 
( DRAX-BIG-ARRONW) 
(STRIPE-ARROWHERD) 
(COMPUTE-NLINES 1869) 
*(COMPUTE-DENS 188@) 


More deiow 


Return to normal debugger, staying in error context. 
Supply replacement argument 

Return a value from the --INTERNAL instruction 
Retry the --INTERNAL instruction 

Lisp Top Level in Lisp Listener 1! 


What Error et arg 
Arglist i Search 


>>Trap: The first argument given to SYS:--INTERNAL, NIL, was not a number. 


pointing at the value 


a je. Ri sect into error hand 
8728783 1?: @2: 8 rom GRA Htc 


Ices fo} ty 


Figure 7. The Display Debugger: inspecting the variable *x2*. 
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(defun do-arrows () 
3; Don’t exceed maximum recursion level 
(when (< *depth* *max-depth*) 
3; Bind values for half and one-fourth of top edge 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4))) 
(draw-arrow) ;Draw a small arrow 
3; Increment depth. Divide top edge in half. Bind new 
3; coordinates for top right point of next arrow. 
(let ((*depth® (1+ *depth*)) 
(*top-edge* *top-edge-2*) 
(*p0x® (+ *top-edge-4* (- *p0x* *top-edge*))) 
(*p0y* (- *p0y* *top-edge-2*))) - 
3; Draw a left-hand child arrow 
(do-arrows) ) 
3; Increment depth. Divide top edge in half. Bind new 
33 coordinates for top right point of next arrow. 
(let ((*depth® (1+ *depth*)) 
(*top-edge*® *top-edge-2*) 
(*p0x* (- *p0x* *top-edge-2*)) 
(*pOy* (+ *top-edge-4* (- *p0y* *top-edge*)))) 
3; Draw a right-hand child arrow 
(do-arrows))))) 


This code produces the result shown in figure 8 (page 81). Something is 
clearly wrong with at least one of the function calls, but the complexity of 
the figure makes it difficult to see the source of the error. We simplify the 
figure by making a comment of the second recursive function call: 
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(defun do-arrows () 
;; Don’t exceed maximum recursion level 
(when (< *depth® *max-depth*) 
3; Bind values for half and one-fourth of top edge 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4))) 
(draw-arrow) ;Draw a small arrow 
3; Increment depth. Divide top edge in half. Bind new 
3; coordinates for top right point of next arrow. 
(let ((*depth*® (1+ *depth*)). 
(*top-edge* *top-edge-2*) 
(*p0x* (+ *top-edge-4*% (- *p0x* *top-edge*))) 
(*pOy* (- *p0y* *top-edge-2*))) 
3; Draw a left-hand child arrow 
(do-arrows) ) 
; Increment depth. Divide top edge in half. Bind new 
; coordinates for top right point of next arrow. 


eo 
> 
° 
5 


#| 
(let ((*depth® (1+ *depth*)) 
(*top-edge* *top-edge-2*) 
(*p0x* (- *p0x* *top-edge-2*) ) 
(*pOy* (+ *top-edge-4* (- *p0y* *top-edge*)))) 
3; Draw a right-hand child arrow 
(do-arrows))))) 
|# : 
»)) 


We recompile do-arrows (using c-sh-C), run the program again, and obtain 
the results shown in figure 9 (page 82). The small arrows now appear to be 
the right size, and the number of recursion levels is correct. The problem 
seems to lie in the positioning of the arrows, or the calculation of the new 
values for *pOx* and *pQy*. On close inspection, we see that the x- 
coordinates look correct, but the y-coordinates are wrong. Instead of 
obtaining the new value of *pOy* by subtracting *top-edge-2* from the old 
*pOy*, we should subtract *top-edge-4* from *pOy*. We change the 
definition of do-arrows: | 
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(defun do-arrows () 


(let ((*depth* (1+ *depth*)) 
(*top-edge* *top-edge-2*) 
(*pOx*® (+ *top-edge-4* (- *p0x* *top-edge*))) 
(*p0y* (- *p0y* *top-edge-4*))) 
;; Draw a left-hand child arrow 
(do-arrows) ) 
33; Increment depth. Divide top edge in half. Bind new 
3; coordinates for top right point of next arrow. 


#| 
(let ((*depth*® (1+ *depth*)) 
(*top-edge* *top-edge-2*) 
(*pO0x® (- *p0x*® *top-edge-2*)) 
(*pOy* (+ *top-edge-4* (- *p0y* *top-edge*)))) 
33; Draw a right-hand child arrow 
(do-arrows))))) 
{# 
))) 


When we recompile do-arrows and run the program again, we obtain the 
results shown in figure 10 (page 83). The first recursive function call is 
now correct. Looking at the arguments in the second function call, we see 
that the same error exists in the calculation of the new *pOx*: We should 
subtract *top-edge-4%, not *top-edge-2*, from the old *pOx*. We make 
the change, remove the #| and |#, and recompile do-arrows. We obtain 
the results shown in figure 1 (page 18). 


Example 

Figure 4 (page 59) shows a split screen, with graphic output in the upper 
window and source code in the lower. To adjust the size of the graphic for 
the smaller window, we have to change the arguments to 
draw-arrow-graphic when we call that function from do-arrow. We want 
to keep a record of the arguments we use to produce a full-screen figure. 
We can make a comment of the call to draw-arrow-graphic that uses full- 
screen arguments: 


. (defun do-arrow () 
(setq *dest* (make-instance *screen-arrow-output) ) 
(send terminal-io °:clear-screen) 

; (draw-arrow-graphic 1280 1800 1800)) 
(draw-arrow-graphic 640 1300 1800)) 
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NIL 
| 2 


Lisp Listener 1 


40/16/7863 ~ 8:58: ron . RAPHI 2 yi 


Figure 8. Output resulting from a faulty attempt to outline the small arrows recursively. 


82 | Program Development Tools and Techniques 
Symbolics, Inc. 


Lisp Listener 1 


Figure 9. Output resulting from a faulty attempt to outline the small arrows recursively, with 
the second function call commented out. 
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Lisp Listener 1 


Figure 10. Output resulting from a corrected attempt to outline the small arrows recursively, 
with the second function call commented out. 
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4.4 Tracing and Stepping 


4.4.1 Tracing 
When a program runs but behaves unexpectedly, you might be calling 
functions in the wrong sequence or passing incorrect arguments. Tracing 
function calls can help detect this sort of problem. By default, tracing 
prints a message, indented according to the level of recursion, on entering | 
and leaving a function. It also prints the arguments passed and the values 
returned. 


You can invoke tracing in three ways: 


Click on [Trace] in the system menu 


Use Trace (m—-X) in Zmacs 
Use the trace special form 


[Trace] and Trace (m~-X%) pop up a menu of options, including stepping and 
inserting breakpoints. You can use these options with trace, too, but the 
syntax is complex. Table 1 (page 87) summarizes the correspondence 
between trace menu items and trace options. See the Lisp Machine Manual, 
section 26.3, page 457, for a description of the options. 


Example 

Suppose that we had begun writing the recursive function calls in do-arrows 
with the following code, passing arguments to do-arrows instead of binding 
the special variables: 


(defun draw-arrow-graphic (*top-edge* *p0x* *p0y*) 


(draw-big-arrow) 
(do-arrows 0 *top-edge-2* (- *p0x*® *top-edge-2*) (- *p0y* *top-edge-2*))) 
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(defun do-arrows (*depth* *top-edge* *p0x* *p0y*) 
3; Don’t exceed maximum recursion level 
(when (< *depth® *max-depth*) 
3; Bind new values for half and one-fourth of top edge 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4))) 
3; Draw a small arrow 
(draw-arrow) 
3; Draw a left-hand child arrow, dividing top edge in half, 
33; incrementing depth, and passing new coordinates for top 
33; right point 
(do-arrows *top-edge-2* (1+ *depth*®) 
(+ *top-edge-4* (- *p0x® *top-edge*)) 
(- *p0y* *top-edge-4*) ) 
3; Draw a right-hand child: arrow, dividing top edge in half, 
33 incrementing depth, and passing new coordinates for top 
33; right point 
(do-arrows *top-edge-2* (1+ *depth*) (- *p0x* *top-edge-4*) 
(+ *top-edge-4* (- *p0y* *top-edge*)))))) 


This code produces only the first of the small arrows. Again, something 
appears to be wrong with the recursive function calls. Using Trace (m-%), 
we trace calls to do-arrows. We run the program again, and the following 
trace output appears: 


(1 ENTER DO-ARROWS (0 640 1160 1160)) 
(2 ENTER DO-ARROWS (320 1 680 1000)) 
(2 EXIT DO-ARROWS NIL) 

(2 ENTER DO-ARROWS (320 1 1000 680)) 
(2 EXIT DO-ARROWS NIL) 


- (1 EXIT DO-ARROWS NIL) 
NIL 


The problem here is immediately apparent: The order of the first two 
arguments in the recursive function calls is reversed. We are passing the 
new value of *top-edge* as the new value of *depth*. Because this value 
exceeds that of *max-depth*, the function returns after the first recursive 
call. 


Reference 

Trace (m-%) Traces or untraces a specified — 
function. Prompts for the name of a 
function to trace and pops up a menu 
of trace options. 

[Trace] (from a system menu) Traces or untraces a specified 


function. Prompts for the name of a 
function to trace and pops up a menu 
of trace options. 
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(trace (:function function-spec-I option-J option-2 ...) ...) 
Enables tracing of one or more 
functions. If function-spec is a 
symbol, the keyword :function is 
unnecessary. An argument can also 
be a list whose car is a list of 
function names and whose cdr is one 
or more options. In this case, all 
functions in the list are traced with 
the same options. With no 
arguments, returns a list of functions 

being traced. 


(untrace (:function function-spec-I) ...) 
Disables tracing of one or more 
functions. If function-spec is a 
symbol, the keyword :function is 
unnecessary. With no arguments, 
untraces all functions being traced. 


4.4.2 Stepping 


When a program behaves unexpectedly and tracing doesn’t reveal the 
problem, you might step through the evaluation of a function call. You can 
step through function execution by using step, [Step] from a trace menu, or 
the :step option to trace. 


You can step through the execution of a function only if it is interpreted, 
not compiled. If you want to step through execution of a compiled 
function, read the definition into a Zmacs buffer and use a Zmacs command 
(such as c-sh-E) to evaluate it (see section 3.2.1, page 66). 


The Stepper prints a partial representation of each form evaluated and the 
values returned. A back arrow («) precedes the representation of each form 
being evaluated. A double arrow (#) precedes macro forms. A forward 
arrow (+) precedes returned values. 


After printing, the Stepper waits for a command before proceeding to the 
next step. Stepper commands allow you to specify the level of evaluation to 
be stepped, escape to the editor, or enter a Lisp breakpoint loop. Press 
HELP inside the Stepper or see the Lisp Machine Manual, section 26.5, 

page 464, for a list of commands. Following are some basic Stepper 
commands: 


Command Action 
c-N Evaluate until next thing to print 
SPACE ; Evaluate until next thing to print at this level (don’t step 


at lower levels) 
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Table 1. Trace Menu Items and trace Options 


Trace menu item 


[Cond break before] 


[Break before] 


[Cond break after] 


[Break after] 
{Error} 


[Step] 

[Cond before] 
[Cond after] 
[Conditional] 
[Print before] 
[Print after] 
[Print] 


[ARGPDL]} 


[Wherein] 


[Untrace] 


trace option 


tbreak predicate 


:break t 


:exitbreak predicate 


sexitbreak t 
serror 


sstep 

sentrycond predicate 
sexitcond predicate 
:cond predicate 
centryprint form 
sexitprint form 
:print form 


zargpdl pal 
:wherein function 
entry /ist 


zexit /ist 


sarg :value sboth :nil 
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Description 

Enters breakpoint on function entry 
if predicate not nil 

Enters breakpoint on function entry 


Enters breakpoint on function exit 
if predicate not nil 


Enters breakpoint on function exit 
Enters Debugger on function entry 


Steps through (interpreted) function 
execution (see section 4.4.2, page 86) 


Prints trace output on function 
entry if predicate not nil 


Prints trace output on function 
exit if predicate not nil 


Prints trace output on function 
entry and exit if predicate not nil 


Prints value of form 


In trace entry output 


Prints value of form 
in trace exit output 


Prints value of form in 
trace entry and exit output 


On function entry, pushes list 
of function name and args onto 
pal, pops list on function exit 


Traces function only when 
called within function 


Calls untrace on function 


Prints values of forms in 
list on function entry 


Prints values of forms in 
list on function exit 


Controls printing of args 
on function entry and values 
on function exit 


8&8 
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e-U Evaluate until next thing to print at next level up (don’t 
step at current and lower levels) 

c-B Enter breakpoint loop 

e-E. Enter Zmacs 

e-X Evaluate until finished (exit from stepping) 

Exampie 


We have the same problem with the function do-arrows as we described in 
section 4.4.1 (page 84). The program outlines only the largest of the small 
arrows, indicating a problem with the recursive function calls. Instead of 


just 


tracing do-arrows, we step through its evaluation. We first use c~sh-E 


to evaluate the definition of do-arrows. We then use [Step] in the menu 
that Trace (m-X) pops up to trace and step through do-arrows. We run 
the program. The Stepper waits for a command before evaluating each 
form in do-arrows. We press SPACE to skip to the next form at the same 
level. When we come to the comparison of *depth* and *max-depth* in 
the recursive calls, we want to see each level of evaluation. We press c-N 
at each of these steps. The tracing and stepping output looks as follows: 


(1 ENTER DO-ARROWS (0 640 1160 1160)) 

# (WHEN (< *DEPTH*® *MAX-DEPTH®) (LET ((*TOP-EDGE-2* (// *TOP-EDGE* 

© (COND ((< *DEPTH*® *MAX-DEPTH*) (PROGN (LET ((*TOP-EDGE-2* (// *T 
(2 ENTER DO-ARROWS (320 1 680 1000)) 


t ¢ 


e 


(WHEN (< *DEPTH® *MAX-DEPTH*) (LET ((*TOP-EDGE-2* (// *TOP-EDGE*® 
(COND ((< *DEPTH* *MAX-DEPTH*) (PROGN (LET ((*TOP-EDGE-2* (// *T 


(< *DEPTH*® *MAX-DEPTH*) 


“© *DEPTH® % 320 


e 


t 


© *MAX-DEPTH*® 7 
(< *DEPTH*® *MAX-DEPTH*) » NIL 


(COND ((< *DEPTH*® *MAX-DEPTH®*) (PROGN (LET ((*TOP-EDGE-2* (// *T » NIL 


(2 EXIT DO-ARROWS NIL) 
(2 ENTER DO-ARROWS (320 1 1000 680)) 


¢ 


t 


e 


e 


(WHEN (< *DEPTH® *MAX-DEPTH®) (LET ((*TOP-EDGE-2* (// *TOP-EDGE* 
(COND ((< *DEPTH*® *MAX-DEPTH®*) (PROGN (LET ((*TOP-EDGE-2* (// *T 


(< *DEPTH® *MAX-DEPTH*) 

© *DEPTH® 4 320 

© *MAX-DEPTH® + 7 

(< *DEPTH® *MAX-DEPTH®) + NIL 


© (COND ((< *DEPTH*® *MAX-DEPTH*) (PROGN (LET ((*TOP-EDGE-2* (// *T > NIL 
(2 EXIT DO-ARROWS NIL) 
(1 EXIT DO-ARROWS NIL) 


NIL 


In this example, stepping shows even more clearly than tracing that the 
value of *depth* is wrong in the recursive function calls. 
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Reference 
(step form) Steps through the evaluation of form 
Trace (m-X) [Step] Steps through the execution of a 


function being traced. 


[Trace / Step] (from a system menu) Steps through the execution of a 
function being traced. 


(trace (:function function-spec :step)) 
Steps through the execution of a 
function being traced. If 
function-spec is a symbol, the keyword 
function is unnecessary. 


4.5 Breakpoints 


In debugging a program, you might want to interrupt function execution to enter a Lisp 
breakpoint loop or the Debugger. Entering the Debugger is usually more useful, for there you 
can examine the stack, return values, and take other steps in addition to evaluating forms. 


You can use two general kinds of breakpoints: 


You can edit into a definition a call to dbg (with no arguments) or to 
break. The advantage of this kind of breakpoint is that, as with stepping, 
you can interrupt execution within the function. The disadvantage is that 
you have to edit and recompile the definition to insert and remove the 
breakpoint. If you redefine the function after inserting the breakpoint, the 
breakpoint might be lost. 


You can use breakon or one of the error or break options to trace. These 
features create encapsulations, functions that contain the basic definitions of 
the functions to which you want to add breakpoints (see the Lisp Machine 
Manual, section 10.10, page 153, for more on encapsulations). The 
advantage of this kind of breakpoint is that when you recompile or 
otherwise redefine the function, only the basic definition is replaced, and the 
breakpoints remain. The disadvantage is that you can interrupt function 
execution only on entry or exit, not within the function. 


You insert these breakpoints by calling breakon or trace from a Lisp 
Listener or by using the trace menu; you remove them by calling 
unbreakon or untrace. When you break on entering function execution, 
just before applying the function to its arguments, the variable arglist is 
bound to a list of the arguments. When you break on exiting from function 
execution, just before the function returns, the venabie values is bound to a 
list of the returned values. 


From either a breakpoint loop or the Debugger, RESUME allows the program to continue, and 
ABORT returns control to the previous break or, if none exists, to top level. 
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Example 

We decide to break on entry to do-arrows and enter the Debugger while 
tracing the function. We use Trace (m-%) and then [Error] from the trace 
menu. We select a Lisp Listener and run the program. On the first entry 
to do-arrows we enter the Debugger, with the following message: 


>> TRACE Break: DO-ARROWS entered. 


DO-ARROWS: (encapsulated for TRACE) 
Rest arg (ARGLIST): (0 640 1160 11690) 
s-A, RESUME: Proceed without any special action 


s-B, ABORT: Lisp Top Level in Lisp Listener 1 

> 

Reference 

(dbg process) Enters the Debugger in process. With 


an argument of t, finds a process that 
has sent an error notification. With 
no argument, enters the Debugger as 
if an error had occurred in the 
current process. 


(break fag conditional-form) Enters a Lisp breakpoint loop 
(identified as “breakpoint tag") if 
Z conditional-form is not nil or is not 
supplied. 


(breakon function-spec conditional-form) 


Passes control to the Debugger on 
entering function-spec if 
conditional-form is not nil or is not 
supplied. With no arguments, returns 
a list of functions with breakpoints 
specified by breakon. 


(unbreakon function-spec conditional-form) 


Turns off the breakpoint condition 
specified by conditional-form for 
function-spec. If conditional-form is 
not supplied, turns off all breakpoints 
specified by breakon for 
function-spec. With no arguments, 
turns off all breakpoints specified by 
breakon for all functions. 


[Error] (from a trace menu) Passes control to the Debugger on 
entering a function being traced. 
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{Cond break before] (from a trace menu) 
Prompts for a predicate. Displays 
trace entry information and enters a 
Lisp breakpoint loop on entering a 
function being traced if the predicate 
is not nil. 


[Cond break after] (from a trace menu) 
Prompts for a predicate. Displays 
trace exit information and enters a 
Lisp breakpoint loop on exiting from 
a function being traced if the 
predicate is not nil. 


(trace (:function function-spec :error)) 
Passes control to the Debugger on 
entering a function being traced. If 
function-spec is a symbol, the keyword 
function is unnecessary. 


(trace (:function function-spec :break predicate)) 
Prints trace entry information and, if 
the value of predicate is not nil, 
enters a Lisp break loop on entering 
the function. If function-spec is a 
symbol, the keyword :function is 
unnecessary. 


(trace (:function function-spec :exitbreak predicate)) 
Prints trace exit information and, if 
the value of predicate is not nil, 
enters a Lisp break loop on exiting 
from the function. If function-spec is 
a symbol, the keyword :function is 
unnecessary. 


4.6 Expanding Macros 


Sometimes a program bug appears to stem from unexpected behavior by a macro. Seeing how 
a macro form expands can help find the bug. To be sure that a macro does what you want it 
to, you might also want to create and expand a macro form soon after defining the macro and 
compiling the definition. 


You can expand a macro form in a Zmacs buffer using Macro Expand Expression (¢-sh-!). 
This command expands the form following point, but not any macro forms within it. To 
expand all subforms, use Macro Expand Expression All (m-X). You can also expand macro 
forms with mexp, which enters a loop to read and expand one form after another. 


Example 
We have just written code to stripe the shafts of the small arrows, drawing 
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stripes with uniform spacing and density. We produce the results shown in 
figure 11 (page 93). We evidently have a problem with the function 
draw-arrow-shaft-stripes. The code for this function is as follows: 


(defun draw-arrow-shaft-stripes 
(left-x top-y right-x bottom-y) 
33; Find y-coord of starting point of stripe. Don’t go 
3; below the bottom cf the triangle. 
(loop for start-y from top-y by *stripe-distance* above bottom-y 
3; Find x-coord of ending point of the stripe 
for end-x from right-x by *stripe-distance* 
3; Draw a stripe 
do (draw-arrow-shaft-lines | 
left-x start-y end-x bottom-y))) 


The bug stems from incorrect coordinates for the endpoints of the shaft 
stripes. The beginning coordinates (left-x and start-y) are correct. The 
ending y-coordinate (bottom-y) looks right, but the ending x-coordinate 
(end-x) is wrong. The problem might not be evident from looking at the 
code, which consists entirely of a loop form. We move to the beginning of 
the loop form and expand it, using c-sh-M: 


((LAMBDA (START-Y 61049 G1050) 
(( LAMBDA (END-X 61051) 
(PROG NIL 
(AND (NOT (GREATERP START-Y G1050)) (GO SI:END-LOOP)) 
SI: NEXT-LOOP 
(DRAW-ARROW-SHAFT-LINES LEFT-X START-Y END-X BOTTOM-Y) 
(SETQ START-Y (DIFFERENCE START-Y G1049)) 
(AND (NOT (GREATERP START-Y G1050)) (GO SI:END-LOOP)) 
(SETQ END-X (PLUS END-X G1051)) 
(GO SI:NEXT-LOOP) 
ST: END-LOOP 
)) 
RIGHT-X 
*STRIPE-DISTANCE*) ) 
TOP-Y 
*STRIPE-DISTANCE® 
BOTTOM-Y) 


The expansion shows the lambda-bindings and prog form that the loop 
macro creates. We can see that the error is in the setting of end-x within 
the prog form: We are incrementing end-x by *stripe-distance*, when we 
should be decrementing it. The problem is in our use of a loop keyword. 
Instead of writing 


for end-x from right-x by *stripe-distance* 


SEES = \ 
WSS 
S Swe N 


WY SA SSEN 


= WNS 


draw-arrow-shaft-stripes. 
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we should have written 


for end-x downfrom right-x by *stripe-distance* 


We make the change and recompile draw-arrow-shaft-stripes. Now if we 
expand the loop form, we see that we are decrementing end-x: 


(( LAMBDA (START-Y G1062 G1063) 
((LAMBDA (END-X G1064) 
(PROG NIL 
(AND (NOT (GREATERP START-Y G1063)) (GO SI:END-LOOP)) 
SI: NEXT-LOOP 
(DRAW-ARROW-SHAFT-LINES LEFT-X START-Y END-X BOTTOM-Y) 
(SETQ START-Y (DIFFERENCE START-Y 61062)) 
(AND (NOT (GREATERP START-Y G1063)) (60 SI:END-LOOP)) 
(SETQ END-X (DIFFERENCE END-X 61064)) 
(GO SI:NEXT-LOOP) 
SIT: END-LOOP 
)) 
RIGHT-X 
*STRIPE-DISTANCE*) ) 
TOP-Y 
*STRIPE-DISTANCE* 
BOTTOM-Y) 


Reference 

Macro Expand Expression (c~sh-M) Expands the macro form following 
point. Does not expand subforms 
within the form. 


Macro Expand Expression All (m-%) Expands the macro form following 
point and all subforms within the 
form. 


(mexp) Enters a loop: prompts for a macro 
form to expand, expands it, and 
prompts for another macro form. 
Exits from the loop on nil. 


4.7 The Inspector 


The Inspector is a window-based tool that combines the describe and disassemble functions. 
Invoke it with inspect, SELECT I, or [Inspect] from a system menu. If you use inspect, the 
Inspector is not a separate activity from the Lisp Listener in which you invoke it. In that case 
you cannot use SELECT L to return to the Lisp Listener; you must click on [Exit] or [Return] 
in the Inspector menu. 


The Inspector displays information about an object and lets you modify the object. It displays 
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information for the last object inspected in the bottom window. It displays information for the 
two previous objects in the windows above the bottom one. It maintains a mouse-sensitive 
listing of all inspected objects in the history window. These are some of its useful features: 


e The information the Inspector displays depends on the object’s type. For a 
symbol, it displays a representation of the value, function, property list, and 
package. For a symbol’s flavor property, it displays information about 
instance variables, component and dependent flavors, the message handler, 
init keywords, and the flavor property list. For a compiled function, it 
displays the disassembled assembly-language code that represents the 
compiler output. 


The Inspector is especially useful for examining data structures. It displays 
the names and values of the slots of structures and, unlike describe, the 
elements of (one-dimensional) arrays. For instances of flavors, the Inspector 
displays the names and values of instance variables. 


Within each display, most representations of objects are mouse sensitive. If 
you click on an object representation, you inspect that object. For example, 
you can inspect elements of lists. If an element of an array is itself an 
array, you can inspect the second array. In this way you can follow long 
paths in data structures. 


You can change a value by using the [Modify] option in the Inspector’s 
menu. You can return a value when you exit the Inspector by clicking on 
[Return]. 


See Operating the Lisp Machine, chapter 5, page 28, for more on the Inspector. 


Example 

Suppose we had represented each arrow as an instance of a structure 
(defined with defstruct) instead of a collection of special-variable values. 

We could have called the structure representing the small arrows arrow and © 
set the value of a special variable, *arr*, to each instance of the structure as 
we created it. 


Figure 12 (page 96) shows an Inspector window for the last arrow in the 
figure. We first run the program in a Lisp Listener, then invoke the 
Inspector using SELECT I. Because we typed (pkg-goto ’graphics) in the 
Lisp Listener, the Inspector’s package is graphics. We type *arr* to the 
interaction pane at the top of the frame. The window at the bottom of the 
frame displays the names and values of the structure slots. We can change 
these values by using the [Modify] menu option. 


Example 

Suppose we had represented each arrow as an instance of a flavor and. 
defined most of our computation functions as flavor methods instead of 
simple functions. We could have called the flavor representing the small 
arrows arrow and set the value of *arr* to each instance of the flavor as 
we created it. 
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#<ARROW -33247021> 


Bottom of History 


Bottom of odject 


Bottom of odject 
Top of odject 
#<CARROW -33247021> 
Named structure of type ARROW 


DEPTH: 6 
TOP-EDGE: 18 
TOP-EDGE-2: 5 
TOP-EDGE-4: 2 
2: 625 
STRIPE-D: 18 
POX: 845 
POY: 215 
P1X: 835 
P1Y: 215 
P2K: 637 
P2Y: 213 
PS: 843 
PSY: 26? 
P6Ks: 645 
P6Y: 285 | 


Bottom of object 
nds function definition. 


oose 8 value by pointing at the value. Right 
Q@8717/783 18:23:32 ron GRAPHICS: Tyi___ 


Figure 12. The Inspector window: inspecting an instance of a structure. 


Program Development Tools and Techniques 97 
Symbolics, Inc. 


Figure 13 (page 98) shows an Inspector window for the last arrow in the 
figure. As with our structure example, we first run the program and then 
invoke the Inspector to evaluate *arr* and inspect the flavor instance that is 
its value. The Inspector displays the names and values of instance variables 
and a representation of the flavor’s message handler. 


We next click on the mouse-sensitive representation of the message handler. 
The Inspector displays a representation of the function spec for the method 
that handles each message. If we click on the function spec for the 
:compute-dens method for flavor basic-arrow, the Inspector displays the 
method’s disassembled code. 


Reference 

(inspect object) Selects an Inspector window in which 
to inspect object. 

SELECT I Selects an Inspector window. 

[Inspect] (from a system menu) Selects an Inspector window. 

(disassemble function) . Prints a representation of the 
assembly-language instructions for a 
compiled function. 

Disassemble (m-X) Prompts for the name of a compiled 


function and displays a representation 
of the function’s assembly-language 
instructions. 
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Top of History | 
#<ARROW 10020842> 


Bottom of History 


Bottom of odject 
Top of odject 


Bottom of odject 
Top of odject 
#<ARROW 10020042) 


fin instance of ARROW. a aaa 


DEPTH: 6 
TOP-EDGE: 10 
TOP-EDGE-2: 5 
TOP-EDGE-4: 2 
K2: 825 
STRIPE-D: 18 
PGK: 845 
POY: 215 
Pix: 835 
PIY: 215 
| P2k: 637 
P2Y: 213 
PSK: 843 
PSY: 207 
P6K: B45 
P6Y: 285 


Bottom of object 


hoose a value by pointing at the value. Banus inds 
88426783 17:69:18 ron GRAPHICS: Tyi 


Figure 13. The Inspector window: inspecting an instance of a flavor. 
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Top of History Exit 
R<ARROW 10620042> Return 
#<Message handler for ARROW> 


Bottom of History 
Top of odject 


Bottom of odject 
Top of odject. 


#<ARROW 10020042> 
An instance of ARROW. &<Message handler for ARROW> 


DEPTH: 6 
TOP-EDGE: 1@ 
TOP-EDGE-2: 5 
More deiow 


ra Top of odject 
#<Message handler for ARROW> 
: COMPUTE-DENS: je" C: METHOD BASTC-ARROW : COMPUTE-DENS) 
:COMPUTE-NLINES: :METHOD BASIC-ARROW :COMPUTE-NLINES) 
:COMPUTE-POINTS: :METHOD BASIC-ARROW :COMPUTE-POINTS) 
:COMPUTE-STRIPE-D: :METHOD BASIC-ARROW :COMPUTE-STRIPE-D) 
:COMPUTE-TOP-EDGES: :METHOD BASIC-ARROW :COMPUTE-TOP-EDGES) 
DESCRIBE: :METHOD SI:VANILLA-FLAVOR DESCRIBE) 
: DRAW-ARROW: :METHOD BASIC-ARROW : DRAW-ARROW) 
: DRAW-ARROW-SHAFT-LINES: :METHOD ARROW-MIKIN : DRAW-ARROW-SHAFT-LINES) 
: DRAW-ARROW-SHAFT-STRIPES: :METHOD ARROW-MIXIN :DRAW-ARROW-SHAFT-STRIPES) 
: DRAW-ARROWHEAD-LINES: :METHOD BASIC-ARROW : DRAW-ARROWHEAD-LINES) 
:DRAW-OUTLINE: :METHOD ARROW-MIXIN :DRAW-OUTLINE) 
:EVAL-INSIDE-YOURSELF: :METHOD SI:VANILLA-FLAVOR :EVAL-INSIDE-YOURSELF) 
:FUNCALL-INSIDE-YOURSELF: :METHOD SI:VANILLA-FLAVOR :FUNCALL-INSIDE~YQURSELF) 
GET-HANDLER-FOR: :METHOD SI: VANILLA-FLAVOR GET-HANDLER-FOR) 
:OPERATIGN-HANDLED-P: sMETHOD SI: VANILLA-FLAVOR :QPERATIOQN-HANDLED-P) 
:PQX: :METHOD BASIC-ARROW :P@X) 
:P@Y: :METHOD BASIC-RRROW :PQY) 
:PRINT-SELF: :METHOD SI:VANILLA-FLAVOR :PRINT-SELF) 
:SEND-IF-HANDLES: :METHOD SI: VANILLA-FLAVOR :SEND-IF~HANDLES) 
:SET-STRIPE-D: :METHOD BASIC-ARROW :SET-STRIPE-D) 
:STRIPE-ARROW-SHAFT : :METHOD ARROW-MIXIN :STRIPE-ARROW-SHAFT ) 
:STRIPE-ARROWHERD: :METHOD BASIC-ARROW :STRIPE-ARROWHERD) 


More delow 


oose 8 value by pointing at the value. Right finds 
08/20/83 17:69:42 rom GRAPHICS: Tyi 


Figure 13, continued. 
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Top of History Exit 
#<ARROW 10028042> Return 
#<Message handler for ARROW> 
#’ (:METHOD BASIC-ARROW :COMPUTE-DENS) 


Bottom of History 
Top of odject — 


#CARROW 100200425 
An instance of ARROW. #<Message handler for ARROW> 


DEPTH: 6 
TOP-EDGE: 18 
JOP-EDGE-2: 5 
More selow 
Top of odject 
#<Message handler for ARROW> 
:COMPUTE-DENS: #?(:METHOD BASIC-ARROW :COMPUTE-DENS) 
:COMPUTE-NLINES: #’? (:METHOD BASIC-ARROW :COMPUTE-NLINES) 
:COMPUTE-POINTS: #’ (METHOD BASIC-ARROW :COMPUTE-POINTS) 
:COMPUTE-STRIPE-D: #? (:METHOD GSASIC-ARROW :COMPUTE-STRIPE-D) 
:COMPUTE-TOP-EDGES: #’? (:METHOD BASIC-ARROW :COMPUTE-TOP-EDGES) 
More selow 


Top of odject 

#<DTP-COMPILED-FUNCTION (:METHOD BASIC-ARROW -:COMPUTE-DENS) 46660073> 

ENTRY: 4 REQUIRED, @ OPTIONAL 

PUSH-INDIRECT *D1* 

PUSH-INDIRECT *D2x 

PUSH-INDIRECT *Dix 

BUILTIN --INTERNAL STACK 

PUSH-LOCAL FPI3 3% 

PUSH~INSTANCE-VARIABLE 2 ;PQX 

BUILTIN --INTERNAL STACK 

PUSH-INSTANCE-VARIABLE 15 3R2] 

PUSH-INSTANCE-VARIABLE 2 3; POX 

BUILTIN --INTERNAL STACK 

BUILTIN FLORT STACK 

BUILTIN ¢“-INTERNAL STACK 

BUILTIN *-INTERNAL STACK 

BUILTIN +-INTERNAL STACK | 

RETURN-STACK 


Bottom of odject 


choose a value by pointing at the value. Right 
68/20/83 17:10:86 rom GRAPHICS 


inds 


Tyi 


Figure 13, concluded. 
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5. Using Flavors and Windows 


All Lisp Machine Lisp programmers must know how to use flavors and the window system in 
at least an elementary way. Flavors are the basis of a powerful, nonhierarchical kind of object- 
oriented programming. Even if you don’t use them extensively, the system code does. 
Applications that include screen display or user interacticn must deal with the window system, 
which is itself built on flavors. 


In this chapter we present a brief introduction to using flavors and windows. We do not 
discuss the concepts and organization of flavors and the window system in any detail. Instead, 
we modify the output module of our example program to show some simple uses of flavors, 
windows, and menus. We show basic examples of the following features: 


e Using base, mixin, and instantiable flavors and :daemon method 
combination 


e Creating a simple window and associating it with a process 
e Producing LGP output 

e Altering values using a choose-variable-values window 

e Signalling a condition and proceeding 


We also present some editor commands and Lisp functions for finding information about 
flavors and windows. Among the issues we do not discuss in any detail are the following: 


e Using types of method combination other than :daemon 
e Interacting with the mouse process | 

e Creating frames 

e Specifying fonts 

e Using menus 


For more information on flavors and windows, read the following documents: 


e On flavors: Lisp Machine Manual, chapter 20, page 279 

e On windows: Introduction to Using the Window System 

¢ On menus: Lisp Machine Choice Facilities 

e On conditions and errors: Signalling and Handling Conditions 


5.1 Program Development: Modifying the Output Module 


As now written, the output routines of our example program consist of a flavor and methods 
that produce lines on the stream to which terminal-io is bound: 


(defflavor screen-arrow-output 
((scale-factor 2.5)) 
()) 


102 Program Development Tools and Techniques 


Symbolics, Inc. 


(defmethod (screen-arrow-output :show-lines) 
(x y &rest x-y-pairs) 

(loop for x0 = (send self *:compute-x x) then xl 
for yO = (send self °*:compute-y y) then yl 
for (xl yl) on x-y-pairs by #’cddr 
do (setq xl (send self °*:compute-x xl) 

yl (send self °’:compute-y yl)) 
(send terminal-io °:draw-line 
x0 yO xl yl tv:alu-ior t))) 


(defmethod (screen-arrow-output :compute-x) (x) 
(fixr (// x scale-factor))) 


(defmethod (screen-arrow-output :compute-y) (y) 
(fixr (- 800 (// y scale-factor)))) 


We want to be able to produce output on the screen, an LGP, or a file. For this we need a 
simple device-independent graphics system that uses generic operations. The central operation is 
:show-lines, which receives endpoint coordinates from the calculation module and produces 
lines on the appropriate output stream. Our general strategy for creating the output options is 
as follows: ' 


1. Define a flavor and methods to calculate the position of the arrow figure on 
the screen or page. We can use this mixin with flavors that produce any 
kind of output. ? 


2. Define flavors and methods to produce screen output. We build the 
instantiable flavors on tv:window and instantiate them with 
tv:make-window. We define two kinds of arrow window flavors: 


e A basic flavor that performs output and redisplays the window after 
changes. 


e A flavor, which we instantiate, that is built on the basic window and 
includes a mixin to convert LGP coordinates to screen coordinates. 


3. Define a flavor and methods to produce LGP or file output. 


4. Define a top-level function that uses a choose-variable-values window to 
select the type of output and alter some variables. The function calls 
tv:make-window or makes an instance of the LGP flavor, depending on the 
output type. 


5. Change the arrow-window flavors to allow multiple windows, associate each 
window with its own process, and allow the user to modify the 
characteristics of the figure in each window. 


6. Define a function to check for mistakes when the user changes the values 
of variables. We define condition flavors for the incorrect choices. We 
define handlers for the conditions and use signal to signal them. We allow 
the user to proceed by supplying new values for the variables. 
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We want to preserve modularity in writing these new routines. We define the flavor that 
positions the arrow figure so that we can use it with any sort of output. We keep the 
operations that transform LGP to screen coordinates separate from the basic window 
operations. We define the routines that handle bad variable values as separate flavors and 
functions. These precautions make it easy to define new kinds of windows or to check for 
errors in other variable values in the future. 


5.1.1 A Mixin to Position the Figure 
No matter what the output device, we want to be sure that the figure fits 
within the bounds of the page or window and is centered within the page or 
window. We define a mixin flavor, arrow-parameter-mixin, with methods 
to perform these calculations. We include this flavor in all flavors that 
produce output for the figure. 


We define five instance variables to hold the parameters. Three of these, 
top-edge, right-x, and top-y, are the arguments we must pass to the 
calculation module. We make these three instance variables gettable so that 
we can retrieve them by sending messages to an instance of the dependent 
flavor. The other two instance variables are the width and height of the 
page or window in the appropriate units, either LGP or screen pixels. 


(defflavor arrow-parameter-mixin 
(width height top-edge right-x top-y) 


() 
(:gettable-instance-variables top-edge right-x top-y) 


(:documentation :mixin 

"Provides parameters for size and position of figure. 
Instance variables hold width and height of page or window; 
length of top edge of figure; coordinates of top right point 
of figure.")) 


The task of this flavor is to perform a generic operation, which we call 
:compute-parameters. This operation consists of separate computations for 
top-edge, right-x, and top-y. We define primary methods for these 
operations here, using coordinates with the origin at bottom left. Flavors 
that mix in this one can add daemons, whoppers, or their own primary 
methods to accommodate other coordinate systems and scale factors. 


We perform these operations as follows: 


1. Determine the width and height of the page or window. The details of this 
operation are the business of other flavors. We specify a required method, 
:compute-width-and-height, for any flavor that mixes in this one. We send 
self a :compute-width-and-height message to set the instance variables. 


2. Calculate a provisional value for top-edge so that the figure fits within the 
smaller dimension of the page or window. We allow the user to specify, by 
setting the global variable *fill-proportion*, what fraction of this dimension 
the figure should fill. . 
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3. Adjust the top edge so that its value is at least 128 and is a multiple of 128 
if larger. This adjustment ensures that stripe spacing is continuous 
throughout the levels of the figure. 


4. Calculate right-x and top-y so that we center the figure within the page or 
window. 


The complete code for this flavor and its methods is as follows: 


(defvar *fill-proportion® 0.9 ‘ 
“Proportion of smaller dimension to be filled by figure") 


(defflavor arrow-parameter-mixin 
(width height top-edge right-x top-y) 


() 
(:gettable-instance-variables top-edge right-x top-y) 
| (:required-methods :compute-width-and-height) 


(:documentation :mixin 

“Provides parameters for size and position of figure. 
Instance variables hold width and height of page or window; 
length of top edge of figure; coordinates of top right point 
of figure. Methods calculate size and position of figure by 
centering it within the page or window and making it fill no 
more than the specified proportion of the smaller dimension. 
The methods use a coordinate system with origin at bottom left; 
other mixins must correct fer this if output is going to a 
window. Other flavors must also provide a method for calculating 
width and height of the page or window. This flavor should be 
mixed into any instantiable flavor that produces output for the 
arrow graphic."“)) 


333 Method controlling calculation of size and position of figure. 
333 Sends messages to self to calculate width and height of page 
333; or window, length of top edge of figure, and coordinates of 
333 figure’s top right point. These are separate methods so that 
$33 other flavors can shadow them or add daemons. Another flavor 
333 must provide a method to compute width and height, because 
333 this is specific to the output device. 
(defmethod (arrow-parameter-mixin :compute-parameters) () 

3; Another flavor must supply. method for width and height 

(send self °:compute-width-and-height) 

3; Make a preliminary estimate of length of top edge 

(send self °’:compute-top-edge) 

3; Adjust top edge to make it a multiple of 128 

(send self °:adjust-top-edge) 

_33 Calculate coordinates of top right point of figure. 

33; We can’t do this until we know how long top edge is. 

(send self °:compute-right-x) 

(send self °:compute-top-y) ) 
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33; Makes a preliminary estimate of length of top edge. 
333 The top edge of the arrow is 80 percent of the horizontal 
$33 or vertical length of the whole figure. First finds the 
333 smaller of the length or width of the page or window. 
333 Multiplies this by the proportion of this dimension that 
333 is to be filled by the figure. The result is the 
333 horizontal or vertical length of the figure. Multiplies 
33; this by 0.8 to get. the length of the top edge. 
(defmethod (arrow-parameter-mixin :compute-top-edge) () 
(setq top-edge 
(fixr (* 0.8 *fill-proportion® (min width height))))) 


333 Adjusts length of top edge so it is a multiple of 128. 
333 There are 64 stripes in the head of the large arrow. The 
333 calculation module divides the length of top edge by two 
333 each time it goes down another recursion level. By making 
333 the original top edge a multiple of 128, we maximize 
333 Continuity in striping between arrowheads and shafts and 
333 among the first several levels of recursion. 
(defmethod (arrow-parameter-mixin :adjust-top-edge) () 
(setq top-edge 
33; Minimum length of top edge is 128 
(if (< top-edge 256) 128 
3; Otherwise set to next lower multiple of 128 
(* 128 (fix (// top-edge 128)))))) 


333 Calculates x-coordinate of top right point of figure. 
333 Finds horizontal length of figure by dividing length of 
333; top edge by 0.8. Centers the figure horizontally within 
333 the page or window. 
(defmethod (arrow-parameter-mixin :compute-right-x) () 
(setq right-x 
(fixr (* 0.5 (+ width (// top-edge 0.8)))))) 


333 Calculates y-coordinate of top right point of figure. 
333; Assumes that the origin is at bottom. Finds vertical 
333 length of figure by dividing length of top edge by 0.8. 
333 Centers the figure vertically within the page cr window. 
(defmethod (arrow-parameter-mixin :compute-top-y) () 
(setq top-y 
(fixr (* 0.5 (+ height (// top-edge 0.8)))))) 


5.1.2 The Basic Arrow Window 


We want to build our window on tv:window, a flavor that produces a 
simple window with borders, a label, and graphics. Any arrow window we 
use must provide for initialization and redisplay, determine its width and 
height, and supply a :show-lines method to draw our figure. 


We define a mixin flavor, basic-arrow-window-mixin, with methods to do 
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these things. We require that this flavor be used with 
arrow-parameter-mixin and tv:window. For the basic window, we assume 
that the coordinates supplied to :show-lines are screen coordinates, with 
origin at top left. 


We write basic-arrow-window-mixin as follows: 


1. Define the flavor. The :required-flavors option ensures that we have 
access to the flavors’ instance variables and that an error will be signalled if 
someone makes an instance of a flavor that includes 
basic-arrow-window-mixin but not the required flavors. The 
:default-init-plist option provides values for some elements of the 
initialization property list in case no one else specifies them. The 
:edges-from option with an argument of ’:mouse allows the user to specify 
the initial size and position of the window by using mouse corners. We give 
an initial minimum width and height for the window because the length of 
top-edge must be at least 128, and we want the entire figure to fit inside 
the window. 


(defflavor basic-arrow-window-mixin () () 
(:required-flavors arrow-parameter-mixin tv:window) 
(:default-init-plist 
:edges-from ’:mouse :minimum-width 200 :minimum-height 2090 
:blinker-p nil :expose-p t) 
(:documentation :mixin 
"Provides for a basic window to display the arrow graphic. 
ARROW-PARAMETER-MIXIN is needed to position the figure within 
the window. This flavor assumes window coordinates, with origin 
at top left.")) 


2. Provide a :show-lines method to draw lines on the screen. We use 
essentially the same methods as in our original output module, but now we 
assume that the arguments are screen coordinates. We define separate 
:compute-x and :compute-y methods to transform the coordinates so that 
we can shadow these methods when we define another flavor to handle LGP 
coordinates. To produce the lines we use the :draw-line method defined 
for tv:graphics-mixin, a component of tv:window. (In :daemon method 
combination, when two component flavors have primary methods for the 
same message, the method of the flavor listed earlier in the component 
ordering shadows, or replaces, the method of the flavor listed later. For 
more on method combination, see the Lisp Machine Manual, section 20.12, 
page 306.) 
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e Receives. endpoint coordinates and draws lines on a window. 
3; Arguments are alternating x- and y-coordinates of the end- 
3; points of lines to be drawn. If there are more than two pairs 
; of coordinates, assumes that the endpoint of one line is the 
; starting point of the next. Sends messages for separate methods 
3; to determine the actual coordinates. This is so that other 
; flavors can modify the coordinates. Draws a line by sending self 
; a :DRAW-LINE message, and so assumes that TV:GRAPHICS-MIXIN is 
333 included somewhere to provide this method. 
(defmethod (basic-arrow-window-mixin :show- lines) 
(x y &rest x-y-pairs) 

3; First determine the starting point of the line. On 
3; subsequent trips through the loop, the last endpoint 
3; becomes the next starting point. 
(loop for x0 = (send self °:compute-x x) then xl 

for’ yO = (send self *:compute-y y) then yl 

33; “Cddr"™ down the list created by making all but the 

33 first pair of ccordinates an &rest argument 

for (xl yl) on x-y-pairs by #’cddr 

3; Determine the endpoint of the line 

do (setq xl (send self °*:compute-x x1) 

yl (send self *:compute-y yl)) 
3; Draw the line 
(send self *:draw-line 
x0 yO xl yl tv:alu-ior t))) 


33; Determines the x-coordinate of an endpoint of a line. 
333 This is a separate method so that other flavors can shadow 
333 it or add daemons to manipulate the coordinate. 
(defmethod (basic-arrow-window-mixin :compute-x) (x) 
(fixr x)) 


33; Determines the y-coordinate of an endpoint of a line. 
333 Assumes that the argument already uses window coordinates, 
333; with origin at top left. This is a separate method so that 
33; other flavors can shadow it or add daemons to manipulate 
333 the coordinate. 
(defmethod (basic-arrow-window-mixin :compute-y) (y) 

(fixr y)) 


3. Supply the :compute-width-and-height method required by 
arrow-parameter-mixin. We use the :inside-size message to 
tv:minimum-window, a component of tv:window. We use muitiple-value 
to set the instance variables width and height. 
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3; Finds the inside width and height of the window. 
3; Sends self an :INSIDE-SIZE message, and so assumes that 
33; TV:MINIMUM-WINDOW is included somewhere to provide this 
333 method. 
(defmethod (basic-arrow-window-mixin 
:compute-width-and-height) () 

(multiple-value (width height) 

(send self ’:inside-size))) 


. Alter the computation of top-y to take account of the screen’s origin at top 


left. We can do this in three ways: 


Define a new primary method for :compute-top-y to shadow the method we 
defined for arrow-parameter-mixin. We would have to be careful to place 
basic-arrow-window-mixin before arrow-parameter-mixin in the list of 
component flavors for any flavor we wanted to instantiate. 


Define :before and :after daemons for :compute-top-y. The :before 
daemon would make top-edge negative and the :after daemon would make 
it positive again. (In :daemon method combination, :before methods for a 
message run before the primary methed, and :after methods run after the 
primary method. If two component flavors have daemons for the same 
message, the :before method of the flavor listed earlier in the component 
ordering runs before the :before method of the flavor listed later, and the 
:after method of the flavor listed earlier runs after the :after method of 
the flavor listed later. For more on method combination, see the Lisp 
Machine Manual, section 20.12, page 306.) 


Define a whopper for :compute-top-y. This would do the same thing as the 
two daemons, except that when all the :compute-top-y methods were 
combined it would run outside any daemons. (A whopper wraps the 
execution of some code around the execution of a method, running before 
all :before daemons and after all :after daemons. For more on whoppers, 
see the System 210 Release Notes, section 7.3, page 41.) 


We define a new primary method in this case because it repeats relatively 
little code and makes the operation of the method clearer. If we used a 
whopper here, someone might mix in another flavor with daemons that 
would unexpectedly run inside our whopper. 


33; Calculates y-coordinate of top right point of figure. 
333 Finds vertical length of the figure by dividing the length 
33; of top edge by 0.8. Centers the figure vertically within 
333; the window. Gives the result in window coordinates, with 
333 origin at top left. This method shadows that in 
333; ARROW-PARAMETER-MIXIN. 
(defmethod (basic-arrow-window-mixin :compute-top-y) () 
(setq top-y 
(fixr (* 0.5 (- height (// top-edge 0.8)))))) 
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5. Calculate the figure’s size and position and redisplay the window at 
appropriate times. We have to recompute the figure’s size and position after 
the window is initialized and after its size or margins change. We have to 
redisplay the figure when the window is refreshed, but only if the window 
has no bit-save array or its size has changed. Before redisplaying, we have 
to clear the screen if the window has a bit-save array. 


We perform these tasks by defining :after daemons for three messages that 
the system can send to a window: :init, :change-of-size-or-margins, and 
refresh. You need daemons like these for most window-system 
applications. 


333; Calculates size and pesition of figure after initialization. 
(defmethod (basic-arrow-window-mixin :after :init) (ignore) 
(send self *:compute-parameters) ) 


333 Calculates size and position of figure after window change. 
(defmethod (basic-arrow-window-mixin 
:after :change-of-size-or-margins) (&rest ignore) 
(send self °:compute-parameters) ) 


33; Draws the figure when necessary after window is refreshed. 
(defmethod (basic-arrow-window-mixin :after :refresh) 
(&optional type) 
3; Draw figure if not restored from a bit-save array ... 
(when (or (not tv:restored-bits-p) 
$3. --- or size has changed. 
(eq type °:size-changed)) 
3; If restored from a bit-save array, clear screen first 
(when tv:restored-bits-p 
(send self °:clear-screen) ) 
3; Bind *DEST*® to self 
(let ((*dest*® self)) 
3; Draw the figure 
(draw-arrow-graphic top-edge right-x top-y)))) 


We can now define a flavor of window, basic-arrow-window, built on our 
two mixin flavors and on tv:window. The order of combination of flavors 
is important. We need to include basic-arrow-window-mixin before 
arrow-parameter-mixin so that the :compute-top-y method for 
basic-arrow-window-mixin shadows that for arrow-parameter-mixin. We 
must also put basic-arrow-window-mixin before tv:window so that our 
:after daemons will run after any that tv:window or its components might 
provide. 
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(defflavor basic-arrow-window () 
(basic-arrow-window-mixin 
arrow-parameter-mixin 
tv: window) 
(:documentation :combination 
“Instantiable flavor providing a basic window for cutput. 
Though this flavor is instantiable, its methods assume that 
point coordinates use the window cocrdinate system, with 
origin at top left. To work with the current calculation 
module it needs another mixin to convert LGP to screen 
coordinates. In the component flavors, BASIC-ARROW-WINDOW-MIXIN 
must come before ARROW-PARAMETER-MIXIN and TV:WINDOW for 
shadowing and daemons to work correctly.")) 


We can actually make an instance of this flavor. We define no new 
methods for it, leaving all methods to component flavors. If we had a 
calculation module that used screen coordinates, basic-arrow-window would 
be the right flavor to use for screen output. 


5.1.3 Converting LGP to Screen Coordinates 
Because our calculation module uses LGP coordinates, we need another 
flavor of window to produce output. We define a flavor, 
lgp-window-mixin, to be mixed in with basic-arrow-window. We need a 
new instance variable, scale-factor, whose value is the ratio of LGP to 
screen pixel densities. 


(defflavor Igp-window-mixin 
((scale-factor 2.5)) 
() 
(:required-flavors basic-arrow-window) 
(:documentation :mixin 
"Converts LGP to screen coordinates and vice versa. 
When mixed in with BASIC-ARROW-WINDOW, this flavor allows 
window output with a calculation module that uses LGP 
coordinates. The instance variable SCALE-FACTOR is the 
ratio of LEP to screen pixel density. The methods take 
the height and width of the window in screen pixels and 
calculate the length of the top edge and the coordinates 
of the top right point of the figure in LGP pixels. In 
drawing lines on the window, the methods convert LGP to 
window coordinates. These methods shadow those in 
ARROW-PARANETER-MIXIN and BASIC-ARROW-WINDOW-MIXIN.")) 


We next define new primary methods to incorporate the scale factor into 
the calculation of top-edge, right-x, and top-y. These methods shadow 
those defined for arrow-parameter-mixin and basic-arrow-window-mixin. 
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33; Calculates top edge in LGP pixels from screen proportions. 
33; Multiplies length of smaller dimension, in screen pixels, by 
$33 proportion of this dimension to be filled by the figure. 
333 Multiplies this by 0.8 to find top edge in screen pixels. 
33; Corrects for higher density of LGP pixels. This method 
333 shadows that of ARROW-PARAMETER-MIXIN. 
(defmethod (lgp-window-mixin :compute-top-edge) () 
(setq top-edge 
(fixr (* scale-factor 0.8 *fill-proportion*® 
(min width height))))) 


33; Calculates x-coord of top right point in L&P pixels. 
333 Finds horizontal length of figure in screen pixels by 
333; dividing top edge by 0.8. Centers figure horizontally 
333 in window, correcting for higher density of LGP pixels. 
333 This method shadows that of ARROW-PARAMETER-MIXIN. 
(defmethod (Ilgp-window-mixin :compute-right-x) () 
(setq right-x 
(fixr (* 0.5 (+ (* width scale-factor) 
(// top-edge 0.8)))))) 


333; Calculates y-coord of top right point in LGP pixels. 
333; Finds vertical length of figure in screen pixels by 
33; dividing top edge by 0.8. Centers figure vertically 
33; in window, correcting for higher density of LGP pixels. 
333 This method shadows those of ARROW-PARAMETER-MIXIN and 
333 BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (ligp-window-mixin :compute-top-y) () 

(setq top-y 

, (fixr (* 0.5 (+ (* height scale-factor) 

(// top-edge 0.8)))})) 


Finally, we need to modify the coordinates used in the :show-lines method 
to take account of the scale factor and the difference in origins for LGP 
and screen coordinates. We define new methods for :compute-x and 
:compute-y to shadow the methods we defined for 
basic-arrow-window-mixin. 


333 Converts x-coord of line endpoint from LGP to screen pixels. 
333; Corrects for higher density of LGP pixels. This method shadows 
333 that of BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (lgp-window-mixin :compute-x) (x) 

(fixr (// x scale-factor))) 


333; Converts y-coord of line endpoint from LGP to screen pixels. 
333; Corrects for higher density of LGP pixels and for screen origin 
333 at top left. This method shadows that of BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (lgp-window-mixin :compute-y) (y) 
(fixr (- height (// y scale-factor))})) 
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We can now define the flavor we will actually instantiate with 
tv:make-window. This flavor, arrow-window, is just a combination of 
lgp-window-mixin and basic-arrow-window. 


(defflavor arrow-window () 
(ligp-window-mixin basic-arrow-window) 

(:documentation :combination 

"“Instantiable flavor for window output from LGP coordinates. 
This fiavor has all the features of BASIC-ARROW-WINDOW but 
assumes that the calculation module uses LGP coordinates. This 
is the flavor to instantiate for window output using the 
current calculation module.")) 


5.1.4 Fiavors for LGP Output 
We want to be able to direct output to an LGP or an LGP record file as 
well as to a window. We define another flavor, lgp-pixel-mixin, to be 
mixed in with arrow-parameter-mixin. We can set an instance variable to 
the output stream and make it inftable so that we can specify the output 
stream when we make an instance of the flavor we build on 
Igp-pixel-mixin. The output stream will itself be an instance of a flavor. 


{defflavor lgp-pixel-mixin 
(output-stream) 
() 
sinitable-instance-var iables 
(:required-flavors arrow-parameter-mixin) 
(:documentation :mixin 
‘“Provides methods for arrow graphic output on an LGP stream. 
ARROW-PARAMETER-MIXIN is required to calculate the size of the 
figure and position it in the center of the page. The method 
assumes that coordinates are in LGP pixels. This flavor 
should be mixed, along with ARROW-PARAMETER-MIXIN, into an 
instantiable fiavor for LGP output. When that flavor is 
instantiated, the instance variable output-stream should be 
initialized.")) 


The methods for this flavor need to do two things: determine the width 
and height of a page and handle :show-lines messages. We get the width 
and height from the values of instance variables for the flavor 
Igp:basic-lgp-stream. This flavor will be a component of the flavor we 
instantiate as the output stream. 
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333; Finds width and height of a page for LGP output. 
333 This flavor is required by ARROW-PARANETER-MIXIN. Finds the 
333 values of two instance variables of LEP:BASIC-LGP-STREAM: 
333 SI:PAGE-WIDTH and SI:PAGE-HEIGHT. Assumes that 
33; LGP:BASIC-LGP-STREAM. is included in output stream to provide 
333; these instance variables. 
(defmethod (lIgp-pixel-mixin :compute-width-and-height) (). 
(setq width (symeval-in-instance output-stream °si:page-width) 
height (symeval-in-instance output-stream ’si:page-height))) 


The :show-lines method is similar to that for windows. Instead of using 
the :draw-line message to produce lines, we use two messages to 
Igp:basic-lgp-stream: :send-command and :send-coordinates. 


333; Receives endpoint coordinates and draws lines on LGP stream. 
333 Arguments are alternating x- and y-coordinates of endpoints of 
33; lines to be drawn. If there are more than two pairs of 
333 coordinates, assumes that the endpoint of one line is the 
$33 starting point of the next. Draws a line by sending output 
$33 Stream :SEND-COMMAND messages for LGP commands and 
333 :zSEND-COORDINATE messages for LGP coordinates. Assumes that 
333 flavor LGP:BASIC-LGP-STREAM is included in output stream to 
333; provide these methods. 
(defmethod (1Igp-pixel-mixin :show-lines) 
(x0 yO &rest x-~-y-pairs) 
s; Send command and coordinates to start ascina: Tines 
(send self °:send-command-and-coordinates #/m x0 yO) 
3; “Cddr"® down the list created by making al! but the first 
3; pair of coordinates an &rest argument 
(loop for (x y) on x-y-pairs by #’cddr 
3; Send command and coordinates to draw a line 
do (send self .’:send-command-and-coordinates #/v x y))) 


333 Sends line-drawing commands to LGP output stream. 

33; :SEND-COMMAND transmits an LGP command. :SEND-COORDINATES 

333. transmits coordinates of an endpoint of a line to be drawn. 

33; Assumes that LGP:BASIC-LGP-STREAM is included in output stream 

333; to provide these methods. 

(defmethod (Igp-pixel-mixin :send- commands and-coordinates) (cmd x y) 
(send output-stream °:send-command cmd): 
(send output-stream ’:send-coordinates (fixr x) (fixr y))) 


We can now define an instantiable flavor for the LGP stream that combines 
lgp-pixel-mixin and arrow-parameter-mixin. 
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(defflavor Igp-pixel-stream () 
(lgp-pixel-mixin arrow-parameter-mixin) 

(:documentation :combination 

"“Instantiable flavor for arrow output on LGP strean. 
Assumes that the calculation module uses LGP coordinates. 
When this flavor is instantiated, the LGP-PIXEL-MIXIN 
instance variable OUTPUT-STREAM should be initialized. 
The cutput stream can be directed to an LGP or a file, 
but it must include flavor LGP:BASIC-LGP-STREAM for 
output to work correctly.")) 


-§.1.5 The Top-Level Function 
We are ready to define a top-level function we can call to produce the 
graphic. We start by popping up a choose-variable-values window. We 
allow the user to specify screen, LGP, or file output. We also allow the 
user to choose values for the number of recursion levels and the proportion 
of the page or window to be filled. We let the user decide whether or not 
to stripe the arrows. 


(defvar *dest-string*® “Screen* 
"Destination of program output [Screen, LGP, or File]") 


| (defvar *output-file® nil 
“Pathname for LGP-record-file output") 


333 Top-level function to call to produce arrow graphic. 
333; Pops up a choose-variable-values window to let user specify 
333 output destination, number of recursion levels, proportion 
333 Of smaller dimension of page or window to be filled, and 
333 whether or not to stripe figure. 
(defun do-arrow () 
:; Pop up a choose-variable-values window 
(tv:choose-var iable-values 
*((*do-the-stripes* "Stripe the arrows?" :boolean) 
(*max-depth*® "Number of recursion levels" :number) 
(*fill-proportion*® 
"Fraction of page or window to be filled" :number) 
(*dest-string* "Output destination" 
:choose ("Screen" “LGP*® "“File")) 
(*output-file*® "Pathname for file output" :PATHNAME)) 
3; Make window wide enough to accommodate long pathnames 
$3; and error messages 
*sextra-width 20. 
3; Give user a chance to abort 
*smargin-choices °("Do It" ("Abort" (signal ’sys:abort))) 
*:label “Choose Options for Graphic") ) 


Next we need to take action depending on the output destination the user 
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has chosen. If the variable *fill-proportion* is zero, we just return nil no 
matter what the output destination. If the destination is "Screen", we make 
an instance of arrow-window. We use tv:make-window, which creates a 
new window each time we call do-arrow. We could also have defined a 
resource of arrow windows (using defwindow-resource), but we might want 
more than one selectable arrow window at a time. 


If we have more than one arrow window, we want each to retain its own 
values for number of recursion levels, proportion of the window to be filled, 
and presence or absence of striping. We define three instance variables for 
basic-arrow-window-mixin and make them initable. We initialize them 
when we call tv:make-window from do-srrow. We change the :after 
daemons for basic-arrow-window-mixin to bind the special variables to the 
instance-variable values. 


(defflavor basic-arrow-window-mixin 
(do-stripes max-dep fill-prop) 
() 
:initable-instance-variables 
(:required-flavors arrow-parameter-mixin tv:window) 
(:default-init-plist 
:edges-from *:mouse :minimum-width 200 :minimum-height 200 
:blinker-p nil :expose-p t) 
(:documentation :mixin ...)) 


(defmethod (basic-arrow-window-mixin :after :init) (ignore) 
(let ((*fill-proportion*® fill-prop) ) 
(send self *:compute-parameters))) 


(defmethod (basic-arrow-window-mixin 
safter :change-of-size-or-margins) (&rest ignore) 
(let ((*fill-proportion*® fill-prop)) 
(send self ’:compute-parameters))) 


(defmethod (basic-arrow-window-mixin :after :refresh) 
(&optional type) 
;; Draw figure if not restored from a bit-save array ... 
(when (or (not tv:restored-bits-p) 
33 «-. Or size has changed. 
(eq type °:size-changed)) 
:; If restored from a bit-save array, clear screen first 
(when tv:restored-bits-p 
(send self *:clear-screen)) 
3; Bind global variables to self and instance variables 
(let ((*dest® self) 
(*do-the-stripes* do-stripes) 
(*max-depth*® max-dep)) 
3; Draw the figure 
(draw-arrow-graphic top-edge right-x top-y)))) 
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(defun do-arrow () 
(tv:choose-variable-values | 


33 If figure is infinitely small, just return nil 
(cond ((= *fill-proportion*® 0) nil) — | 
33 If screen output, make a window 
((equal *dest-string* “screen") 
(tv:make-window ’arrow-window 
33; Initialize instance variables to 
3; values set by the user 
*:do-stripes *do-the-stripes* 
*smax-dep *max-depth*® 
*:fill-prop *fill-proportion*®) ))) 


If the output destination is "LGP" or "File", we want to make an instance 
of lgp-pixel-stream with the instance variable stream initialized to an 
appropriate stream. We construct this stream by calling 
si:make-hardcopy-stream with an argument that depends on the output 
destination. We use with-open-stream to produce the output on the stream 
and close it when we finish. | 
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(defun do-arrow () 
(tv: choose-var iable-values 


(cond ((= *fill-proportion® 0) nil) 
3; If screen output, make a window 
((equal *dest-string* “screen") 
(tv:make-window ’arrow-window 
3; Initialize instance variables to 
3; values set by the user 
*:do-stripes *do-the-stripes* 
>smax-dep *max-depth*® 
*:fill-prop *fill-proportion*) ) 
3; If LGP or file output, use an appropriate stream 
(t (with-open-stream 
(stream 
3; This function returns a stream suitable for 
3; LGP output 
(si:make-hardcopy-stream 
3; Argument is the output device. For LGP, 
3; use the default hardcopy device. 
(if (equal *dest-string*® "Igp") 
si:*default-hardcopy-device*® 
3; For file output, use the correct format 
3; for the hardcopy device and direct 
3; output to the file specified by tha user 
(lgp:get-Igp-record-file-hardcopy-device 
*output-file*®)))) 
3; Make an instance of our LGP output flavor 
(let ((*dest*® 
(make-instance °’Ilgp-pixel-stream 
3; Initialize instance 
33; variable to output stream 
*:output-stream stream) )) 
3; Position the figure on the page 
(send *dest® °:compute-parameters) 
3; Draw the figure, using instance-variable values 
$3; aS arguments 
(draw-arrow-graphic (send *dest* °:top-edge) 
(send *dest* *:right-x) 
(send *dest* *:top~y))))))) 


5.1.6 The Arrow Window: Interaction, Processes, and the Mouse 
Suppose we want to let the user modify the characteristics of the graphic 
for each window. The user might want to change the presence or absence 


of striping, the number of recursion levels, or the proportion of the window 
to be filled. 


One way to install this option is to associate each window with its own 
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process and let the process run in a loop. If the user clicks right on the 
window, we pop up a choose-variable-vaiues window. When the user is 
finished, we refresh the window and wait for the next mouse click. 


We can associate a window with a process by including the flavor 
tv:process-mixin in basic-arrow-window. When we make the window 
(using tv:make-window), we specify a :process init option whose argument 
is the name of the top-level function for the process. When the window is 
created, a new process Is created as well. When the window is exposed, the 
process’s top-level function is called with one argument, the window. 


(defflavor basic-arrow-window () 
(basic-arrow-window-mixin 
arrow-parameter-mixin 
| tv:process-mixin 
tv: window) 
(:documentation :combination ...)) 


(defun do-arrow () 
(tv: choose-var iable-values 


(cond ((= *fill-proportion® 0) nil) 

3; If screen output, make a window 

((equal *dest-string*® "screen") 

(tv:make-window ’arrow-window 

33 Initialize instance variables to 

33; Values set by the user 
*:do-stripes *do-the-stripes* 
*smax-dep *max-depth* 
*:fill-prop *fill-proportion*® 
3; Specify top-level function for the 
33 Process associated with the window 
*:process °(window-loop))) 


We next want to be able to handle mouse clicks. We include the flavors 
tv:any-tyi-mixin and tv:list-mouse-buttons-mixin in basic-arrow-window. 
When a window is waiting for input and the mouse is clicked while over the 
window, a blip enters the window’s input buffer. A blip is a list whose 
form, with tv:list-mouse-buttons-mixin, is as follows: 


(:mouse-button encoded-click window x y) . 


Encoded-click is a fixnum that represents the button clicked. 


Program Development Tools and Techniques 119 


Symbolics, Inc. 


(defflavor basic-arrow-window () 

(basic-arrow-window-mixin 
arrow-parameter-mixin 
tv:any-tyi-mixin 
tv: list-mouse-buttons-mixin 
tv:process-mixin 
tv: window) 

(:documentation :combination ...)) 


We also want a mouse documentation string to appear when the mouse is 
over the window: 


(defmethod (basic-arrow-window-mixin 
:who-line-documentation-string) () 
"Provides a mouse documentation line for the window. 
The only option is to click right and pop up a 
choose-var iable-values window of options for changing 
the graphic on this window." 
*R: Choose-variable-values options for changing figure on this window") 


We can now write the process function window-loop. This function just 
sends a :main-loop message to the window. We define :main-loop as a_ 
method for basic-arrow-window-mixin. The method consists of an 
error-restart-loop so that we can return to top level if sys:abort or an 
error is signalled. We send the window an :any-tyi message. If the user 
clicks right, we pop up a choose-variable-values window with the window’s 
current value of the variables. When the user exits, we refresh the window 
and wait for another click. If the user aborts, sys:abort is signalled, and we 
restart the loop. 


333 Top-level function for process associated with arrow window. 
333 The function is called when the window is created. Argument is 
333 the window. The function sends the window a :MAIN-LOOP message. 
33; This method should be the actual command loop for the process. 
(defun window-loop (window) 

(send window °*:main-loop) ) 
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333; Command loop for window associated with a separate process. 
33; Consists of an error-restart-loop that handles restarts from errors 
333 and sys:abort. Waits for mouse input. If a right click, pops up a 
333; choose-variable-values window to change characteristics of the 
333; figure. On exit, sets instance variables to the new values and 
33; refreshes the window, then waits for another mouse click. Assumes 
33; blips are lists of the form provided by TV:LIST-MOUSE-BUTTONS-MIXIN. 
(defmethod (basic-arrow-window-mixin :main-loop) () 
3; Run forever in a loop. Offer a restart handler if an error 
3; or SYS:ABORT is signalled. 
(error-restart-loop ((error sys:abort) “Arrow Window Top Level") 
3; Wait for input 
(let ((char (send self *:any-tyi))) 
3; Pop up window if input is a list ... 
(when (and (listp char) 
. 33 --. and a mouse click ... 
(eq (first char) °*:mouse-button) 
33 -.- and a single click on the right button. 
(eq (second char) #\mouse-r-1)) 
3; Bind global variables to instance-variable values 
(let ((*do-the-stripes* do-stripes) 
(*max-depth*® max-dep) 
(*fill-proportion® fi11-prop)) 
3; Pop up a choose-variable-values window 
(tv:choose-var iable-values 
*((*do-the-stripes* "Stripe the arrows?" :bcolean) 
(*max-depth® "Number of recursion levels" :number) 
(*fill-proportion® 
"Fraction of window to be filled" :number)) 
3; Make the window wide to provide enough room for error 
33 Messages. 
*sextra-width 20 
3; Give the user a chance to abort 
*smargin-choices °("Do It" ("Abort" (signal ’sys:abort))) 
*:label "Choose Options For Graphic") 
3; Set instance variables to the new values - 
(setq do-stripes *do-the-stripes*® 
max-dep *max-depth*® 
fill-prop *fill-proportion*®) 
3; Recompute size and position of the figure 
(send self °:compute-parameters) 
3; Send :REFRESH message with argument of ’:new-vals to make 
3; sure the figure is redrawn if there is a bit-save array 
(send self °:refresh *:new-vals)))))) 


We need to change the :after :refresh method for 
basic-arrow-window-mixin so that it redraws the figure when the values 
are changed even if the window has a bit-save array. 
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(defmethod (basic-arrow-window-mixin :after :refresh) 
(&optional type) 
3; Draw figure if not restored from a bit-save array ... 
(when (or (not tv:restored-bits-p) 
33 «-. or Size has changed ... 
(eq type °:size-changed) 
$3 .-- or new values for figure parameters. 
(eq type *’:new-vals)) 
3; If restored from a bit-save array, clear screen first 
(when tv:restored-bits-p 
(send self °:clear-screen)) 
3; Bind global variables to self and instance variables 
(let ((*dest*® self) 
(*do-the-stripes*® do-stripes) 
(*%max-depth® max-dep) ) 
3; Draw the figure 
(draw-arrow-graphic top-edge right-x top-y)))) 


Note that we can also manipulate the windows we create by using the 

[Split Screen] and [Edit Screen] options from a system menu. We might 
have more than one arrow window on the screen at the same time. We 
might redisplay the figures on these windows at the same time. In this case, 
the scheduler might switch between the arrow window processes, allowing 
each to run for a time until all redisplays are complete. 


Remember that we took care to bind rather than set the global variables in 
the calculation module that hold the state of each arrow. We want the 
values of some variables to be different in each window. Each process 
maintains its own bindings for variables. When the scheduler switches 
processes, bindings in the old process are undone and saved. They are 
restored when the old process resumes. But if we had set the variables, the 

_ program would not have run correctly when the scheduler switched 
processes. The new process might have used variable values set in the old 
process. | 


5.1.7 Signalling Conditions | 
We want to add one more refinement to the output module. In our choose- 
variable-values windows, the variable type keywords, such as :number and 
:pathname, provide for some error checking when users choose new values. 
But two of our numeric variables have further restrictions: *max-depth* 
must be a nonnegative integer, and *fill-proportion* must be a fraction 
between 0 and 1. 


The function tv:choose-variable-values has a :function option that lets us 
name a function to be called whenever an item is to be changed. We can 
use this function to check the values of our two variables and signal a 
condition if the values are bad. We then print a message on the window 
and ask the user to proceed by supplying a new value. 
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We start by defining flavors for the conditions we signal. We define a 
general class of error conditions called bad-arrow-variable. We then define 
two flavors built on bad-arrow-variable: bad-arrow-depth for improper 
values of *max-depth* and bad-arrow-fill-proportion for improper values 
of *fill-proportion*. For each of these instantiable flavors we define a 
sreport method and a :proceed method. The :report method prints a 
string identifying the condition. The :proceed method allows the user to 
proceed from the condition, in this case by supplying a new value. We 
could have more than one :proceed method if we had other ways of 
proceeding. s:proceed methods are combined using :case method 
combination. 


If we want to create conditions for bad values of other variables in the 
future, we can simply define new flavors built on bad-arrow-variable. 


(defflavor bad-arrow-variable () (error) 

(:documentation 

"“Noninstantiable class of bad-variable conditions. 
The user might set some variables to impermissible values. 
These conditions are to permit checking for bad values 
beyond the system’s error checking. Instantiable condition 
flavors for specific variables should be built on this 
flavor .")) 


(defflavor bad-arrow-depth () (bad-arrow-variable) 
(:documentation 
"“Proceedable condition: bad value for *MAX-DEPTH?. 
An instantiable condition flavor for impermissible values 
of ‘*MAX-DEPTH®, the number of recursion levels in the 
figure.")) 


33; Prints string on stream to report bad *MAX-DEPTH*® value 
(defmethod (bad-arrow-depth :report) (stream) 
(format stream "No. of levels was not a ~ 
nonnegative fixnum.")) 


333; Proceed type method for supplying new value of *MAX-DEPTH® 
(defmethod (bad-arrow-depth :case :proceed :new-depth) 
(&optional (dep (prompt-and-read 
* snumber 
"Supply new value for ~ 
no. of recursion levels: "))) 
“Supply a new value for number of recursion levels." 
(values *:new-depth dep) ) 
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(defflavor bad-arrow-fill-proportion () (bad-arrow-variable) 
(:documentation 
“Proceedable condition: bad value for *FILL-PROPORTION®. 
An instantiable condition flavor for impermissible values of 
*FILL-PROPORTION*, the fraction of the smaller dimension of 
the page or window that the figure is to fill.")) 


333 Prints string on stream to report bad *FILL-PROPORTION* value 
(defmethod (bad-arrow-fill-proportion :report) (stream) 
(format stream “Proportion was not a fraction between ~ 
0 and 1.")) 


333; Proceed type method for new value of *FILL-PROPORTION*® 
(defmethod (bad-arrow-fill-proportion :case :proceed 
snew-proportion) 
(&optional (prop (prompt-and-read 
*snumber 
"Supply new fraction of bounds ~ 
be filled: "))) 
"Supply a new fraction of page or window to be filled.* 
(values *:new-proportion prop) ) 


Next we write the function, check-item, to be called when a variable value 
is changed. The function is called with four arguments: the choose- 
variable-values window, the variable, and the variable’s old and new values. 
We use condition-bind to bind a handler for our two conditions. This 
handler will be called if we signal the conditions from within the 
condition-bind. If we do find a bad variable value, we we expect the call 
to signal to return the two values from the :proceed method: the proceed 
type and the new variable value. We then check the new value and, if it is 
good, set the variable to the new value. Finally, we refresh the window and 
return tf. 
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; Called when a value changes in choose-variable-values window. 
333; Arguments are the window, the variable, and its old and new values. 
333; Binds handlers for conditions for impermissible values. If new 
333 value is OK, sets variable to the new value, refreshes window, and 
333 returns t. If value is not OK, signals the appropriate condition. 
33; When SIGNAL returns, presumably with a new variable value, checks 
; the new value in the same way it checks a new value that comes 
333 from the window. 
(defun check-item (cvv-window var old-val new-val) 
33; We don’t use the old value. To avoid a compiler complaint, 
3; just evaluate it and ignore it. We coutd also use IGNORE 
33; instead of OLD-VAL in the arglist, but then the arglist 
3; would be less meaningful. 
old-val 
3; Bind handlers for the conditions we might signal 
{condition-bind ((bad-arrow-depth ’bad-arrow-var-handler) 
(bad-arrow-fill-proportion 
*bad-arrow-var-handler ) ) 
(when (eq var °’*max-depth®) 
33; *MAX-DEPTH® must be nonnegative fixnum 
(loop until (and (fixp new-val) (2 new-val 0)) 
33; If it’s not, bind QUERY-IO to the window and 
33; signal a condition. SIGNAL should return 
33 two values, the proceed type and the new 
3; value from the proceed method. Ignore the 
33; proceed type and set NEW-VAL to the new 
33; value. 
do (let ((query-io cvv-window) ) 
(multiple-value (nil new-val) 
(signal *bad-arrow-depth))))) 
(when (eq var °*fill-proportion*®) 
3; *FILL-PROPORTION® must be between 0 and 1 
(loop until (and (2 new-val 0) (Ss new-val 1)) 
33; If it’s not, bind QUERY-IO to the window and 
3; signal a condition. SIGNAL should return 
3; two values, the proceed type and the new 
33; value from the proceed method. Ignore the 
3; proceed type and set NEW-VAL to the new 
$3 value. 
do (let ((query-io cvv-window) ) 
(multiple-value (nil new-val) 
(signal *bad-arrow-fill-proportion))))) 
3; Variable value is now OK. Set variable to the new value. 
3; Note that we DO want to evaluate VAR. 
(set var new-val) 
3; Refresh the window 
(send cvv-window °:refresh) 
3; Return t 


t)) 


Next we need to add the :function option to our calls to 
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tv:choose-variable-values in the function do-arrows and the :main-loop 
method of basic-arrow-window-mixin: 


(defun do-arrow () 
3; Pop up a choose-variable-values window 
(tv:choose-var iable-values 
*((*do-the-stripes* “Stripe the arrows?" :boolean) 
(*max-depth® “Number of recursion levels" :number) 
(*fill-proportion*® 
“Fraction of page or window to be filled" :number) 
(*dest-string® "Output destination® 
:choose ("Screen“ "LGP* "File®)) 
(*output-file* “Pathname for file output" :pathname)) 
3; Make window wide enough to accommodate long pathnames 
3; and error messages 
*:extra-width 20. 
3; Call this function when a value is changed 
*:function *check-item 
3; Give user a chance to abort 
*:margin-choices °("Do It" (*Abort" (signal *sys:abort))) 
*: label “Choose Options for Graphic") 
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(defmethod (basic-arrow-window-mixin :main-loop) () 
3; Run forever in a locp. Offer a restart handler if an error 
3; or sys:abort is signalled. 
(error-restart-loop ((error sys:abort) "Arrow Window Top Level") 
3; Wait for input 
(let ((char (send self ’:any-tyi))) 
3; Pop up window if input is a list ... 
(when (and (listp char) 
$3 «-. and a mouse click ... 
(eq (first char) *:mouse-button) 
$3... and a Single click on the right button. 
(eq (second char) #\mouse-r-1)) 
3; Bind global variables to instance-variable values 
(let ((*do-the-stripes*® do-stripes) 
(*max-depth*® max-dep) 
(*fi1l-proportion® fill-prop)) 
3; Pop up a choose-variable-values window 
(tv: choose-var iable-values 
*((*do-the-stripes* "Stripe the arrows?" :boolean) 
(*max-depth* "Number of recursion levels" :number) 
(*fill-proportion® 
"Fraction of window to be filled" :number)) 
33; Make the window wide to provide enough room for error 
$3 messages. 
*sextra-width 20 
3; Call a function to check for errors when values. change 
*:function *check-item 
33; Give the user a chance to abort 
*smargin-choices °("Do It® ("Abort" (signal ’sys:abort))) 
*:Tabel "Choose Options for Graphic") 
3; Set instance variables to the new values 
(setq do-stripes *do-the-stripes*® 
max-dep *max-depth? 
fill-prop *fill-proportion*®) 
s; Recompute size and position of the figure 
(send self °:compute-parameters) 
33; Send :REFRESH message with argument of *:new-vals to make 
33; sure the figure is redrawn if there is a bit-save array 
(send self °’:refresh °:new-vals)))))) 


Finally, we need to write a handler for the two conditions. When a 
condition is signalled, the handler is called with one argument, the object of 
the flavor of condition that is signalled. In check-item, we call signal with 
query-io bound to the choose-variable-values window. The handler checks 
to be sure there is a proceed type for the object. If so, the handler turns 
on a blinker on the window and sends the :report and :preceed messages to 
the condition object. Finally, it turns off the blinker and passes back to its 
caller the two values that the :proceed method returns. 
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Actually, the handler we define doesn’t depend on the binding of query-io 
to the window. If query-io is not bound to a window — that is, to an 
instance of a flavor built on tv:sheet —- the handler won’t try to turn on a 
blinker. If query-io is bound to a window, the handler first looks (using 
tv:sheet-following-blinker) for an existing blinker that follows the cursor. 
If it doesn’t find one, it makes a new blinker (using tv:make-blinker). It 
encloses the handling operation in an unwind-protect to be sure that the 
blinker is turned off in case of a nonlocal exit. 


333; Handler for bad value of *MAX-DEPTH® or *FILL-PROPORTION®?. 
333 Argument is the condition object created by SIGNAL. Uses QUERY-IO 
333 stream to report condition. Sends the condition object a :PROCEED 
333 message and passes back the values it returns. 
(defun bad-arrow-var-handler (cond-obj &aux b1) 
3; Find out whether this object has the right proceed type. 
3; If not, return nil. 
(if (send cond-obj °:proceed-type-p 
{cond (({typep cond-obj *bad-arrow-depth) °:new-depth) 
((typep cond-obj "*bad-arrow-fill-proportion) 
* :new-proportion))) 
3; Enclose the handling operation in an UNWIND-PROTECT so that 
3; if we use a blinker we are sure to turn it off 
(unwind-protect 
(progn 
3; Use a blinker if the QUERY-IO stream is a window 
(setq bl (if (typep query-io ’tv:sheet) 
s: If a cursor-following blinker exists, use it 
(or (tv:sheet-following-blinker query-io) 
3; Otherwise, make a new blinker 
(tv:make-blinker query-io 
*tv:rectangular-bl inker 
*:follow-p t)))) 
3; If a blinker, make it blink 
(if bl (send bl ’:set-visibility °:blink)) 
3; Alert the user 
(tv: beep) 
33; Send a report, presumably describing the condition 
(send cond-obj ’:report query-io) 
33; Send object a :PROCEED message and return the values 
3; that the methcd returns 
(send cond-obj °:proceed 
(cond ((typep cond-obj ’bad-arrew-depth) ° :new-depth) 
((typep cond-ebj ’bad-arrow-fill-proportion) 
*:new-proportion)))) 
33; If a blinker, turn it off 
(if bl (send bl °:set-visibility nil))))) 


After we have defined all the flavors and methods for the output module, 
we insert a compile-flavor-methods form in the file. Without this macro, 
combined methods are compiled and flavor data structures generated when 
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we make the first instance of a flavor — that is, at run time. 
compile-flavor-methods speeds run-time operation by causing combined 
methods to be compiled at compile time and data structures to be generated 
at load time. It is useful only for flavors that will be instantiated, not for 
flavors that are only components of instantiated flavors. 


(compile-flavor-methods arrow-window Igp-pixel-stream 
bad-arrow-depth bad-arrow-fill-proportion) 


5.2 Programming Aids for Flavors and Windows 


Some editor commands and Lisp functions provide information about flavors. You can find out 
about component flavors, methods, instance variables, init keywords, and documentation. Using 
the Inspector, you can examine instance variables and methods for instances of flavors (see 
section 4.7, page 94). If a flavor has gettable instance variables, you can obtain their values by 
sending messages to instances of the flavor. 


These commands and functions are useful for finding information about windows as well. 
Because windows are instances of flavors, you can retrieve characteristics that are stored in 
gettable instance variables by sending messages to the windows (see Introduction to Using the 
Window System). If a window is exposed, you can examine and alter some characteristics by 
clicking on the [Attributes] item in the system menu. Clicking on [Attributes] pops up a 
choose-variable-values window for such characteristics as font, label, margins, and vertical 
spacing between lines. 


As with other definitions, Edit Definition (m-.) prepares to edit definitions of flavors and 
methods. Section 5.2.2 (page 129) describes how to use this command to edit method 
definitions. 


5.2.1 General Information 
The facilities that display general information about a flavor are Describe 
Flavor (m-X) and describe-flavor. These display somewhat different 
descriptions of a flavor. 


A useful predicate for instances of flavors is typep. Given an instance and 
a flavor name, typep returns t if the instance includes the flavor as a 
component. 


Example 

In handling bad values for the variables *max-depth* and 
*fill-proportion*, we want to be sure that query-io is bound to a window 
before turning on a blinker. We find out whether the object bound to 
query-io is built on tv:sheet by using typep: 


(typep query-io ’tv:sheet) 
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Reference 
Describe Flavor (t-X) Displays a description of a flavor that 
: includes the names of instance 

variables and component flavors and 
any documentation added by the 
:documentation option to defflavor. 
Also displays init keywords and 
inherited methods and instance 
variables. Names of flavors and 
methods in the display are mouse 
sensitive. 


(describe-flavor flavor-name) Prints a description of a flavor that 
includes the names of instance 
variables and component flavors and 
any documentation added by the 
:documentation option to defflavor. 


(typep arg type) When arg is an instance of a flavor 
| and type is a flavor name, returns t if 
the instance includes the flavor as a 
component or nil if it does not. If 
type is omitted, returns a symbol 
representing the flavor of the 
instance. 


5.2.2 Methods 


Four Zmacs commands display information about the methods that handle 
messages to instances of flavors. For instances of flavors built on 
si:vanilla-flavor — that is, for nearly all flavors — you can send messages 
to find out which messages the object handles and whether or not it handles 
a specific message. 


You can use the Zmacs command Edit Definition (m-.) to edit the 
definition of a method. Specify a method by typing a representation of its 
function spec. This is a list of the following form: 


(:method flavor type message) 


When typing this representation for Edit Definition (m-.), type is optional. 
If the method has a type, Zmacs will try to find the definition and ask you 
whether or not that definition is the one you want. 


You might know the name of a method but not the name of its flavor. Use 
List Methods (m-X) to find methods for ali flavors that handle a message. 
You can click on one of the method names displayed to edit its definition. 
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. Example 
We want to edit the definition of the :main-loop method for 
basic-arrow-window-mixin. We use Edit Definition (m-.) and type: 


(:method basic-arrow-window-mixin :main-loop) 


Example 

We want to find out which methods handle :show-lines messages and how 
the methods handle the messages. List Methods (m-X) displays the following 
methods: 


Methods for :SHOW-LINES 
(:METHOD BASIC-ARROW-WINDOW-MIXIN :SHOW-LINES) 
(:METHOD LGP-PIXEL-MIXIN :SHOW-LINES) 


We can click on one of the method names or press c-. to edit the 
definition. We also could have found the source code directly by using Edit 
Methods (m-%). 


Example 

We want to find out which methods are called when the system sends an 
sinit message to arrow-window. List Combined Methods (m-X) prompts for 
message and flavor names and displays the following methods, in the order 
in which they are called: 


* Combined method for :INIT message to ARROW-WINDOW flavor 
:METHOD TV:SHEET :WRAPPER : INIT) 

sMETHOD TV:STREAM-MIXIN :BEFORE :INIT) 

:METHOD TV:BORDERS-MIXIN :BEFORE : INIT) 

:METHOD TV:ESSENTIAL-LABEL-MIXIN :BEFORE : INIT) 
:METHOD TV:ESSENTIAL-WINDOW :BEFORE : INIT) 
:METHOD TV:SHEET :INIT) 

:METHOD TV:ESSENTIAL-SET-EDGES :AFTER :INIT) 
:METHOD TV:LABEL-MIXIN :AFTER : INIT) 

:METHOD TV:PROCESS-MIXIN :AFTER : INIT) 

:METHOD BASIC-ARROW-WINDOW-MIXIN :AFTER : INIT) 


OE Ee EE 


Reference 

List Methods (m-X) Lists methods for all flavors that 
handle a specified message. Press c-. 
to edit the definitions of the methods 
listed. 


Edit Methods (m-X) Prepares to edit definitions of 
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methods for all flavors that handle a 
specified message. Press c~. to edit 
subsequent definitions. 


List Combined Methods (m-%) Lists all the methods that would be 
called if a specified message were sent 
to an instance of a specified flavor. 
Press c-. to edit the definitions of 
the methods listed. 


Edit Combined Methods (m-X) Prepares to edit definitions of 
methods that would be called if a 
specified message were sent to an 
instance of a specified flavor. Press 
c-. to edit subsequent definitions. 


(send instance ’:which-operations) Returns a list of messages that 
instance can handle. 


(send instance ’:operation-handled-p message) 
Returns t if instance has a handler for 
message or nil if it does not. 


(get-handler-for object message) Returns the method that handles 
message to object, or nil if object has 
no handler for message. 


§.2.3 Init Keywords .- 
si:flavor-allowed-init-keywords retrieves the init keywords allowed for a 
flavor. 


Example 
We want to find the allowed init keywords for lgp-pixel-stream. 
si:flavor-allowed-init-keywords returns the following list: 


(:DO-STRIPES :FILL-PROP :MAX-DEP :OUTPUT-STREAM) 


These are all keywords for initable instance variables, the first three from 
arrow-parameter-mixin and the last from lgp-pixel-mixin. 


Reference 

(si:flavor-allowed-init-keywords flavor-name) 
Returns a list of any init keywords a 
flavor can take. 
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Appendix A 
Calculation Module for the Sample Program 


The program used as an example in this document draws the recursive arrow graphic on the 
document’s cover. This appendix contains Lisp code that calculates coordinates for the 
endpoints of the lines that compose the figure. The code produces output by sending messages 
to instances of flavors defined in another file. Appendix B (page 147) contains the code for 
the flavors and methods that mediate between the program and the system output operations. 
Appendix C (page 165) contains a reproduction of the LGP graphic the program produces. 


333 7*- Mode: LISP; Package: (GRAPHICS GLOBAL 1000); Base: 10 -*- 
333 Copyright (c) 1983 Symbolics, Inc. 


#| 

This file contains the calculation module for a program that 
reproduces the recursive arrow graphic printed on the covers 
cof most Symbolics documents. The module calculates the 
coordinates of the endpoints of line segments to be drawn. 
It transmits these coordinates to a separate output module, 
which contains the code needed to produce the figure on an 
appropriate output device. 


We use paper coordinates, origin at bottom left. 


Each arrow in the figure can be seen as inscribed in a square 
whose apex is at (apex-x, apex-y). Each arrow has a head and 
a shaft. Top-edge is the top edge of each arrow, one of the 
sides of the arrowhead. There are two classes of arrow in 
the figure: The small arrows are the general case, and the 
Jarge, outer arrow is unique. The differences are the 
structures of the shafts and the recursive appearance of 

the small arrows. 


The module uses special variables to store information about 
the current arrow, including the length of the top edge and 
the coordinates of the vertexes. 


The module first calculates coordinates for the vertexes of 
the large, outer arrow. If the arrows are to be striped, it 
determines the endpoints of the lines that make up the large 
arrow’s stripes, first in the head and then in the shaft. 
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The module then recursively calculates coordinates for each of 
the smal? arrows inside the figure. It outlines and stripes 
one arrow at a time. For each arrow, the module first 
calculates the coordinates of the vertexes of the head. If the 
arrows are to be striped, it then determines the coordinates of 
the endpoints of the lines that make up the current arrow’s 
Stripes, first in the head and then in the shaft. 


The output module initiates the calculation module by calling 
DRAW-ARROW-GRAPHIC with three arguments: the length of the 
figure’s top edge and the coordinates of the top right point 

(pO in the large arrow). This module transmits coordinates to 

the output module by sending :SHOW-LINES messages to instances 

of output flavors. The arguments to :SHOW-LINES are the 
coordinates of the endpoints of lines to be drawn. The current 
instance of the output flavor is the value of the special variable 


*DEST*. 
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Points 3 and 4 are obscured, except in the case of the big arrow. 
|# 


333 Following are declarations for special variables and constants 


(defconst *d1* 0.15 
"Proportion of distance filled in between upper right stripes") 


(defconst *d2* 0.75 
“Proportion of distance filled in between lower left stripes") 


(defconst *stripe-distance*® 20 
“Horizontal distance in pixels between stripes of large arrow") 


(defconst *max-depth® 7 
“Number of levels of recursion") 


(defconst *do-the-stripes® t 
"If T, permits striping") 


(defconst *dest*® nil 
“Object to which output is sent") 


(defvar *depth® 0 
"Current level of recursion") 


(defvar *top-edge® nil 
“Length of the top edge of the arrow") 


(defvar *top-edge-2* nil 
“Half the length of the top edge of the arrow") 


(defvar *top-edge-4* nil 
"One-fourth the length of the top edge of the arrow") 


(defvar *x2* nil 
"X-coord of projection of lower left stripe on top edge") 


(defvar *stripe-d* nil 
“Horizontal distance in pixels between stripes") 


(defvar *p0x* nil 
"X-coordinate of the tip of the arrow") 


(defvar *p0y* nil 
“Y-coordinate of the tip of the arrow") 


(defvar *plx® nil 
"X-coordinate of point pl in the arrow") 
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(defvar *ply*® nil 
"Y-coordinate of point pl in the arrow") 


(defvar *p2x* nil 
"X-coordinate of point p2 in the arrow") 


(defvar *p2y* nil 
"Y-coordinate of point p2 in the arrow") 


(defvar *p3x* nil 
"X-coordinate of point p3 in the arrow") 


(defvar *p3y* nil 
"Y-coordinate of point p3 in the arrow") 


(defvar *p4x*® nil 
"X-coordinate of point p4 in the arrow") 


(defvar *p4y* nil 
"Y-coordinate of point p4 in the arrow") 


(defvar *p5x* nil 
"“X-coordinate of point p5 in the arrow") 


(defvar *p5y* nil 
"Y-coordinate of point p5 in the arrow") 


(defvar *p6x* nil 
"X-coordinate of point p6 in the arrow") 


(defvar *p6y* nil 
"Y-coordinate of point p6 in the arrow") 


333; Following are the controlling functions for this module 
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; Function controlling the calculation module. 

; Controls the calculation of the coordinates of the endpoints of the 

; lines that make up the figure. The three arguments are the length of 

; the top edge and the coordinates of the top right point of the large 

; arrow. DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW to draw the large arrow 


and then calls DO-ARROWS to draw the smaller ones. 


(defun draw-arrow-graphic (*top-edge*® *p0x* *p0y*) 
33; Bind global variables 
(let ((*top-edge-2* (// *top-edge* 2)) 


(*top-edge-4* (// *top-edge*® 4)) 
3; Compute horizontal distance between stripes in the large 
33; arrow, assuming 64 stripes in the large arrowhead. 
(*stripe-distance*® (// *top-edge* 64))) 
(draw-big-arrow) ;Draw large arrow 
3; Length of the top-edge for the first small. arrow is half the 
3; length for the large arrow. Bind new coordinates for the top 
33; right point of the small arrow. 
(let ((*top-edge* *top-edge-2*) 
(*p0x*® (- *p0x* *top-edge-2*)) 
(*pOy* (- *p0y* *top-edge-2*)) 
(*depth® 0)) 
(do-arrows)))) ;Draw small arrows 


; Recursive function controlling drawing of the small arrows. 

; If below the maximum recursion level, draws a small arrow. Binds 
33; new values for depth, top edge, and coordinates of top right point, 
3 and calls self recursively to draw a left-hand child arrow. Binds 
; special variables again and calls self to draw a right-hand child 


arrow. 


(defun do-arrows () 


Don’t exceed maximum recursion level 


(when (< *depth® *max-depth*) 


33; Bind values for half and one-fourth of top edge 
(let ((*top-edge-2* (// *top-edge* 2)) 
(*top-edge-4* (// *top-edge* 4))) 
(dr aw-arrow) ;Draw a small] arrow 
3; Increment depth. Divide top edge in half. Bind new 
3; coordinates for top right point of next arrow. 
(let ((*depth® (1+ *depth*) ) 
(*top-edge* *top-edge-2*) 
(*p0x* (+ *top-edge-4* (- *p0x® *top-edge*))) 
(*p0y* (- *p0y* *top-edge-4*))) 
3; Draw a left-hand child arrow 
(do-arrows ) ) 
3; Increment depth. Divide top edge in half. Bind new 
3; coordinates for top right point of next arrow. 
(let ((*depth® (1+ *depth*)) 
(*top-edge* *top-edge-2*) 
(*pOx*® (- *p0x* *top-edge-4*) ) 
(*pOy* (+ *top-edge-4* (- *p0y* *top-edge*)))) 
3; Draw a right-hand child arrow 
(do-arrows))))) 
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333 The following functions are common to the large and small arrows 


333 Calculates coordinates of points visible in large and small arrows. 
3; The four points that bound the head of each arrow are the only ones 
333 visible in the small arrows. Points 3 and 4 -- the base of the arrow 
333 77 are obscured, except in the large arrow. We calculate these in 
$33 Ccompute-arrow-shaft-points. 

(defun compute-arrowhead-points () 


(let*® ((plx (- *p0x* *top-edge*) ) 3;X-coord, point 1 
(ply *p0y*) 3Y-coord, point 1 
(p2x (+ plx *top-edge-4*)) 3;X-coord, point 2 
(p2y (- *p0y* *top-edge-4*)) 3Y-coord, point 2 
(p6x *p0x*) 3;X-coord, point 6 
(p6y (- *p0y* *top-edge*)) sY-coord, point 6 
(p5x (- *p0x® *top-edge-4*)) 3X-coord, point 5 
(p5y (+ p6y *top-edge-4*))) 3Y¥-coord, point 5 


(values plx ply p2x p2y p5x p5y p6x pé6y))) 


3:3; Calculates horizontal distance between stripes. 
33; Distance is a fraction of the distance between stripes for the 
$+; large arrow. The divisor depends on the level of recursion. 
33; Distance divides length of top edge evenly when possible to 
333; maintain continuity between head and shaft of arrow. 
(defun compute-stripe-d () 
3; Distance should be at least 3 pixels so that there is some 
3; white space between lines. 
Cif (s *stripe-distance*® 3) 3 
3; First find a fraction of *STRIPE-DISTANCE® that depends 
$3; on recursion level 
(loop for dist = (fixr (// *stripe-distance*® 
(selectq *depth*® 
(0 2) 
(1 4) 
(2 2) 
(3 1.5) 
(4 1.5) 
_ (otherwise 2)))) 
33; Increment if it doesn’t divide *TOP-EDGE* evenly 
then (1+ dist) 
when (= 0 (\ *top-edge* dist) ) 
3; Stop when no remainder. Don’t return a value 
3; less than 3. 
do (return (if (< dist 3) 3 dist))))) 
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; Calculates the number cof lines that compose each stripe. 
; Calls COMPUTE-DENS to calculate the proportion of distance 
; between stripes to be filled, then multiplies by the actual 


distance between stripes. Makes sure that there is at least 
one line and that there aren’t too many lines to leave some 
white space. 


(defun compute-nlines (x) 
3; Call COMPUTE-DENS and multiply result by *STRIPE-D* 
(let ((nl (fix (* *stripe-d* (compute-dens x))))) 


3; Supply at least one line 

(cond ((s nl 1) 1) 
;; But leave some white space between Tines 
((2 nl (- *stripe-d* 1)) (- *stripe-d* 2)) 
(t n1)))) 


; Calculates proportion of distance filled in between each stripe. 

; The argument is the x-coordinate of the projection of the current 

; stripe onto the line formed by the top edge. Determines where the 
; projection of the current stripe is on this line in relation to the 
; distance from first to last stripes in the arrow. Multiplies this 
; fraction by the difference between densities of first and last 


stripes. Finally, adds the density of the first stripe. 


(defun compute-dens (x) 
(+ *dl* (* (- *d2* *d1*) 


(// (- x *p0x*) (float (- *x2* *p0x*)))))) 


; The following two functions stripe the arrowheads. The 


33; heads of the large and small arrows are identical, so we 


; use the same functions to stripe both. 


; Function controlling striping of the head of each arrow. 

; Determines coordinates of starting and ending points for each 
; stripe. Calls COMPUTE-NLINES to determine number of lines for 
; the stripe. Calls DRAW-ARROWHEAD-LINES to draw the lines that 
333; Make up each stripe. 


(defun stripe-arrowhead () 
3; Find x-coord of top of last stripe to be drawn 
(loop with last-x = (- *p0x* *top-edge*) 


3; Find starting x-coord for each stripe, decrementing 

3; by distance between stripes. Stop at last x-coord. 

for start-x from *pCx* by *stripe-d* above last-x 

3; Find ending y-coord for each stripe, decrementing by 
3; distance between stripes. 

for end-y downfrom *p0y* by *stripe-d* 

33; Find number of lines in the stripe 

for nlines = (compute-nlines start-x) 

3; Draw the lines that make up the stripe 

do (draw-arrowhead-lines nlines start-x end-y last-x))) 
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33; Draws the lines that make up each stripe in an arrowhead. 
33; Arguments are number of lines in the stripe, starting x-coord 
333 and ending y-coord of first line, and x-coord of top of last 
333 stripe to be drawn. Decrements by one pixel when drawing each 
333 line. 
(defun draw-arrowhead-lines (nlines start-x end-y last-x) 
3; Set up a counter 
(loop for i from 0 below nlines 
33; Find starting x-coord, subtracting counter from first 
33; x-coord 
for first-x = (- start-x i) 
3; Make sure we don’t go past the end of the arrowhead 
while (< last-x first-x) 
3; Draw a line 
do (send *dest*® °:show-lines 
first-x *p0y* *p0x* (- end-y i)))) 


333 The following functions draw and stripe the large arrow 


333; Function controlling drawing of the large arrow. 
33; Calls functions to find coordinates of vertexes of the arrow. 
333; Outlines the arrow. Binds distance between stripes and x-coord 
333 of projection of last stripe onto top edge. Finally, stripes 
3:3; head and shaft of arrow when required. 
(defun draw-big-arrow () 
3; Determine coordinates of arrowhead vertexes 
(multiple-value-bind 
(*plx® *ply* *p2x* *p2y* *p5x® *p5y* *pGx* *p6y*) 
(compute-arrowhead-points) 
3; Determine coordinates of shaft vertexes 
(multiple-value-bind 
(*p3x* *p3y* *p4x* *p4y*) 
(compute-arrow-shaft-points) 
(draw-big-outline) ;Outline arrow 
(when *do-the-stripes* 
3; Bind distance between stripes and x-coord of projection 
3; of last stripe onto top edge 
(let ((*stripe-d* *stripe-distance*) 
(#x2® (- *p0x* *top-edge* *top-edge*))) 
(str ipe-arrowhead) ;Stripe head 
(stripe-big-arrow-shaft)))))) ;Stripe shaft 


33; Calculates coordinates for vertexes of shaft of large arrow. 
333; These points are obscured and not drawn for the small arrows. 
(defun compute-arrow-shaft-pcints () 


(values (- *plx* *top-edge-4*) 3X-coord of point 3 
(- *p2y* *top-edge-2*) 3;Y-coord of point 3 
*p2x* ;X-coord of point 4 


(- *p2y* *top-edge*®))) ;Y-coord of point 4 
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:3;; Draws the outline of the large arrow. 
(defun draw-big-outline () 
(send *dest* °:show-lines 
*p0x*® *p0y* *plx® *plys *p2x*® *p2y* &p3x* tp3y* 
*p4x* *p4y* *p5x® *p5y* *p6x® *p6y* *p0x® *p0y*)) 


333 The next seven functions stripe the shaft of the large arrow. 
333 First is a controlling function, then three functions to stripe 
333; the left side and three more to stripe the right. 


333 Function controlling striping of the shaft of the large arrow. 
333; Just calls STRIPE-BIG-ARROW-SHAFT-LEFT to stripe the left side 
333 and STRIPE-BIG-ARROW-SHAFT-RIGHT to stripe the right side. 
(defun stripe-big-arrow-shaft () 

(str ipe-big-arrow-shaft-left) 

(stripe-big-arrow-shaft-right) ) 


333; Function controlling striping of left side of big arrow’s shaft. 
333; Iterates over the triangles that make up the shaft. Determines 
33; coordinates of the apex and bottom right point of each triangle. 
333; Calls DRAW-BIG-ARROW-SHAFT-STRIPES-LEFT to stripe each triangle. 
(defun stripe-big-arrow-shaft-left () 
3; Set up a counter for depth. Don’t exceed maximum recursion 
3; level. 
(loop for shaft-depth from 0 below *max-depth* 
3; Find current top edge and its fractions 
for top-edge = *top-edge* then (// top-edge 2) 
for top-edge-2 = (// top-edge 2) 
for top-edge-4 = (// top-edge 4) 
3; Find coordinates of apex of triangle 
for apex-x = *p2x* then (- apex-x top-edge-2) 
for apex-y = *p2y* then (- apex-y top-edge-2) 
3; Find x-coord of bottom right vertex 
for right-x = (+ apex-x top-edge-4) 
3; Find y-coord of bottom edge of triangle 
for bottom-y = (- apex-y top-edge-4) 
3; Find the x-coord of the projection cf the first 
3; stripe onto top edge . 
for xoff = (- *p0x*® *top-edge*) then (- xoff top-edge) 
3; Stripe each triangle 
do (draw-big-arrow-shaft-stripes-left 
top-edge-4 apex-x apex-y right-x bottom-y xoff))) 
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333; Stripes each triangle in left side of big arrow’s shaft. 
3; Arguments are one-fourth current top edge, x- and y-coords 
3; of apex of triangle, x- and y-coords of bottom right vertex, 
; and x-coord of projection of first stripe onto top edge. 
3; Determines coordinates of starting and ending points for 
333 each stripe. Finds number of lines in the stripe. Calls 
3; DRAW-BIG-ARROW-SHAFT-LINES-LEFT to draw the lines that 
$33 make up each stripe. 
(defun draw-big-arrow-shaft-stripes- -left 
(top-edge-4 apex-x apex-y right-x bottom-y xoff) 
en with half-distance = (// *stripe-distance* 2) 
3; Find x-coord of last stripe in triangle 
with last-x = (- apex-x top-edge-4) 
3; Find x-coord of top of each stripe, decrementing 
33 from the apex by HALF the horizontal distance 
33; between stripes. Stop at last stripe. 
for start-x from apex-x. by half-distance above last-x 
33 Find y-coord of top of stripe 
for start-y downfrom apex-y by half-distance 
33; Find x-coord of endpoint cf stripe 
for end-x downfrom right-x by *stripe-distance* 
3; Find number of lines in the stripe 
for nlines = (compute-nlines (- xoff (- right-x end-x))) 
3; Draw a stripe 
do (draw-big-arrow-shaft-lines- left 
niines start-x start-y end-x bottom-y last-x))) 


333; Draws the lines for a stripe on left side of big arrow’s shaft. 
333; Arguments are number of lines in the stripe, cceords of starting 
333 and ending points for first line, and x-coord of last stripe to 
333; be drawn. 
(defun draw-big-arrow-shaft-lines-left 

(nlines start-x start-y end-x end-y last-x) 

3; Set up two counters -- we need to draw two lines at once 
(loop for i from 0 

for i2 from 0 by 2 

3; Find x-coord of top of first line in stripe 

for first-x = (- start-x i) 

s; Don’t exceed number of lines in stripe 

while (< 12 nlines) 

33 Don’t go past the end of the triangle 

while (< last-x first-x) 

;; Draw a line 

do (send *dest* °:show-lines first-x (- start-y 1) 

(- end-x i2) end-y) 

;; Draw a second line. The two lines are a refinement 

3; to stagger the endpoints of the lines so the diagonal 

33; edge looks neat. 

. (send *dest*® ’:show-lines first-x (- start-y i 1) 
(- end-x i2 1) end-y))) 
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$33 Function controlling striping of right side of big arrow’s shaft. 
33; Iterates over the triangles that make up the shaft. Determines 
333; coordinates of the top point of each triangle. Calls 
333; DRAW-BIG-ARROW-SHAFT-STRIPES-RIGHT to stripe each triangle. 
(defun stripe-big-arrow-shaft-right () 
3; Set up a counter for depth. Don’t exceed maximum recursion 
33; level. 
(loop for shaft-depth from 0 below *max-depth* 
33; Find new top edge and its fractions 
for top-edge = *top-edge* then (// top-edge 2) 
for top-edge-2 = (// top-edge 2) 
for top-edge-4 = (// top-edge 4) 
33; Find coords of top point of triangle 
for start-x = (+ "p2x* top-edge-4) 
for top-y = (- *p2y* *top-edge-4*) 
then (- top-y top-edge-2 top-edge-4) 
3; Find x-coord of projection of first stripe onto 
3; top-edge 
for xoff = (- *p0x* *top-edge*) then (- xoff top-edge) 
3; Stripe the triangle 
do (draw-big-arrow-shaft-stripes-right 
top-edge-2 top-edge-4 start-x top-y xoff))) 


33; Stripes each triangle in right side of big arrow’s shaft. 
333; Arguments are one-half and one-fourth of current top edge, 
33; coords of top point of the triangle, and x-coord of projection 
333; of first stripe onto top edge. Determines coordinates of 
$33; starting and ending points for each stripe. Finds number of 
333 lines that make up the stripe. Calls 
333; DRAW-BIG-ARROW-SHAFT-LINES-RIGHT to draw a stripe. 
(defun draw-big-arrow-shaft-stripes-right 
(top-edge-2 top-edge-4 start-x top-y xoff) 
(loop with half-distance = (// *stripe-distance*® 2) 
33; Find y-coord of last stripe in triangle 
with last-y = (- top-y top-edge-2) 
33; Find y-coord of starting point of stripe. Don’t go 
33 past the end of the triangle. 
for start-y from top-y by *stripe-distance* above last-y 
33; Find coords of ending point of the stripe, decrementing 
3; by HALF the horizontal distance between stripes 
for end-x downfrom (+ start-x top-edge-4) by half-distance 
for end-y downfrom (- top-y top-edge-4) by half-distance 
3; Find number of lines that make up the stripe 
for nlines = (compute-nlines (- xoff (- top-y start-y))) 
3; Draw a stripe 
do (draw-big-arrow-shaft-lines-right 
nlines start-x start-y end-x end-y last-y))) 
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33; Draws the lines for a stripe on right side of big arrow’s shaft. 
333 Arguments are number of lines in the stripe, coordinates of starting 
333 end ending points for the first line, and y-coord of last stripe in 
333 the triangle. 
(defun draw-big-arrow-shaft-lines-right 
(nlines start-x start-y end-x end-y last-y) 
3; Set up two counters -- we need to draw two lines at once 
(loop for i from 0 
for i2 from 60 by 2 
3; Find y-coord of ending point of line 
for stop-y = (- end-y i) 
3; Don’t exceed number of lines in the stripe 
while (< i2 nlines) 
3; Don’t go past the bottom of the triangle 
while (< last-y stop-y) 
;; Draw a line 
do (send *dest* °:show-lines start-x (- start-y i2) 
(- end-x i) stop-y) 
3; Draw a second line. The two lines are a refinement 
3; to stagger the endpoints of the lines so the diagonal 
3; edge looks neat. 
(send *dest* °:show-lines start-x (- start-y i2 1) 
(- end-x i 1) stop-y))) 


$33 The remaining functions draw and stripe one of the small arrows 


333 Function controlling drawing of a small arrow. 
33; Calculates coordinates of the arrowhead and outlines it. Binds x-coord 
333 of the projection of the last stripe onto the top edge. Calculates 
333; the horizontal distance between stripes. When necessary, stripes the 
333; head and shaft of the arrow. 
(defun draw-arrow () 
3; Calculate coordinates of arrowhead vertexes 
(multiple-value-bind 
(*plx® *ply® *p2x*® *p2y® *p5x* *p5y* *&p6x*® *p6y*) 
(compute-arrowhead-points) 
3; Outline the arrowhead 
(draw-outline) 
(when *do-the-stripes*® 
3; Bind x-coord of projection of last stripe onto top edge 
(let ((*x2*® (- *p0x* *top-edge* *top-edge*) ) 
3; Calculate distance between stripes 
(*stripe-d* (compute-str ipe-d) )) 
(str ipe-arrowhead) ;Stripe head 
(str ipe-arrow-shaft))))) sStripe shaft 


33; Draws the outline of the head of a small arrow. 
(defun draw-outline () 
(send *dest* ’:show-lines *p2x*® *p2y* *plx® *ply*® 
*p0x*® *p0y* *p6x* *p6y* *p5x* sp5y*)) 
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33; Function controlling striping of the shaft of a small arrow. 
:3; Iterates over the descending triangles that make up the shaft. 
333 Calculates the coordinates of the top left and bottom right 
333 vertexes of each triangle. Finds the x-coord of the 
333 projection of the first stripe onto top edge. Calls 
333; DRAW-ARROW-SHAFT-STRIPES to stripe each triangle. 
(defun stripe-arrow-shaft () 
3; Set up a counter for depth. Don’t exceed maximum 
3; recursion level. 
(loop for shaft-depth from *depth* below *max-depth* 
3; Calculate fractions of new top edge 
for top-edge-2 = *top-edge-2* then (// top-edge-2 2) 
for top-edge-4 = (// top-edge-2 2) 
3; Find coords of top left point of triangle 
for left-x = *p2x* then (- left-x top-edge-4) 
for top-y = *p2y* then (- top-y top-edge-2 top-edge-4) 
33; Find coords, of bottom right point of triangle 
for right-x = (+ left-x top-edge-2) 
for bottom-y = (- top-y top-edge-2) 
3; Find x-coord of projection of first stripe onto top edge 
for xoff = (- *p0x* *top-edge*) 
then (- xoff top-edge-2 top-edge-2) 
3; Stripe the triangle 
do (draw-arrow-shaft-stripes 
left-x top-y right-x bottom-y xoff))) 


: Stripes each triangle in the shaft of a small arrow. 
; Arguments are coordinates of the top left and bottom right 
33; points of the triangle, and the x-coord of the projection 
:3:3; of the first stripe onto top edge. Calculates the y-coord 
: of the starting point and the x-coord of the ending point 
33; Of each stripe. Finds number of lines in the stripe. Calls 
33; DRAW-ARROW-SHAFT-LINES to draw the lines in the stripe. 
(defun draw-arrow-shaft-stripes 
(left-x top-y right-x bottom-y xoff) 

3; Find y-coord of starting point of stripe. Don’t go 

3; below the bottom of the triangle. 

(loop for start-y from top-y by *stripe-d* above bottom-y 
3; Find x-coord of ending point of the stripe 
for end-x downfrom right-x by *stripe-d* 
33; Find number of lines in the stripe 
for nlines = (compute-nlines (- xoff (- right-x end-x))) 
3; Draw a stripe 
do (draw-arrow-shaft-lines 

nlines left-x start-y end-x bottom-y) )) 
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333; Draws the lines in a stripe in the shaft of a small] arrow. 
333; Arguments are the number of lines in the stripe and the 
$33; coordinates of the starting and ending points of the first line. 
(defun draw-arrow-shaft-lines 
(nlines left-x start-y end-x bottom-y) 
3; Set up a counter. Don’t exceed number of lines in the stripe. 
(loop for {i from 0 below nlines 
3; Find x-coord of ending point of the line 
for last-x = (- end-x i). 
3; Don’t go past the left edge of the triangle 
while (< left~-x last-x) 
3; Draw a line 
do (send *dest* °:show-lines left-x (- start-y i) 
last-x bottom-y) )) 
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Appendix B 
Output Module for the Sample Program 


The program used as an example in this document draws the recursive arrow graphic on the 
document’s cover. This appendix contains Lisp code that defines the flavors and methods that | 
mediate between the program and the system output operations. Appendix A (page 133) 
contains the code that calculates coordinates for the endpoints of the lines that compose the 
figure. Appendix C (page 165) contains a reproduction of the LGP graphic the program 
produces. 


333 7*- Mode: LISP; Package: (GRAPHICS GLOBAL 1060); Base: 10 -*- 
333; Copyright (c) 1983 Symbolics, Inc. 


#| 

This file contains the output module for a program that 
reproduces the recursive arrow graphic printed on the covers 
of most Symbolics documents. The module allows the graphic 
to be produced on a Lisp Machine screen, a Laser Graphics 
Printer, or an LGP record file. For each of these devices, 
the module produces output by sending appropriate messages 
with the coordinates of the endpoints of line segments to 

be drawn. This module receives these coordinates from a 
separate calculation module. 


For screen output, the module creates its own windows. It: 
defines a basic flavor of window that accepts point 
coordinates in the screen coordinate system, with origin 

at top left. It defines a more specialized window, built 
on the basic window, for use with a calculation module that 
uses LGP coordinates, with origin at bottom left. It 
allows a process to be associated with each window and 

lets users modify the characteristics of the figure. 


For LGP output, the module makes an instance of a flavor 
with the output stream as an instance variable. Output is 
directed to either a hardcopy device or a record file. 


This module defines the top-level function, DO-ARROW, that 
is called to produce the graphic. This function pops up 

a choose-variable-values window to allow users to select the 
output device and the characteristics of the figure. The 
module defines conditions and handters for attempts to give 
variables impermissible values. 
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This module determines the size of the figure and its 
position within the page or window. It then calls the 
function DRAW-ARROW-GRAPHIC in the calculation module. 

It passes as arguments the length of the top edge of the 
figure and the coordinates of the top right point. The 
calculation module sends :SHOW-LINES messages to instances 
of output flavors. The arguments to :SHOW-LINES are the 
‘coordinates of the endpoints of lines to be drawn. The 
current instance of the output flavor is the value of the 
special variable *DEST*. 

|# 


333 Following are declarations for special variables 


(defvar *dest-string® "Screen" 
"Destination of program output [Screen, LGP, or File]*) 


(defvar *output-file*® nil 
“Pathname for LGP-record-file output") 


(defvar *fill-proportion® 0.9 
“Proportion of smaller dimension to be filled by figure") 


333 The following flavor and its methods are common to both 
333. screen and LGP output 


(defflavor arrow-parameter-mixin 
(width height top-edge right-x top-y) 
() : 
(:gettable-instance-variables top-edge right-x top-y) 
(:required-methods :compute-width-and-height) 
(:documentation :mixin 
“Provides parameters for size and position of figure. 
Instance variables hold width and height of page or window; 
length of top edge of figure; and coordinates of top right point 
of figure. Methods calculate size and position of figure by 
centering it within the page or window and making it fill no 
more than the specified proportion of the smatler dimension. 
The methods use a coordinate system with origin at bottom left; 
other mixins must correct for this if output is going to a 
window. Other flavors must also provide a method for calculating 
width and height of the page or window. This flavor should be 
mixed into any instantiable flavor that produces output for the 
arrow graphic.")) 
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333; Method controlling calculation of size and position of figure. 
333; Sends messages to self to calculate width and height of page 
33; or window, length of top edge of figure, and coordinates of 
333 figure’s top right point. These are separate methods so that 
333 other flavors can shadow them or add daemons. Another flavor 
$33; must provide a method to compute width and height, because 
333; this is specific to the output device. 
(defmethod (arrow-parameter-mixin :compute-parameters) () 

3; Another flavor must supply method for width and height 

(send self *:compute-width-and-height) 

3; Make a preliminary estimate of length of top edge 

(send self °:compute-top-edge) 

3; Adjust top edge to make it a multiple of 128 

(send self °:adjust-top-edge) 

3; Calculate coordinates of top right point of figure. 

3; We can’t do this until we know how long top edge is. 

(send self °*:compute-right-x) 

(send self *:compute-top-y)) 


333; Makes a preliminary estimate of length of top edge. 
333; The top edge of the arrow is 80 percent of the horizontal 
; or vertical length of the whole figure. First finds the 
333 smaller of the length or width of the page or window. 

; Multiplies this by the proportion of this dimension that 
333 is to be filled by the figure. The result is the 
33; horizontal or vertical length of the figure. Multiplies 
333 this by 0.8 to get the length of the top edge. 
(defmethod (arrow-parameter-mixin :compute-top-edge) () 

(setq top-edge 

(fixr (* 0.8 *fill-proportion® (min width height))))) 


333; Adjusts length of top edge so it is a multiple of 128. 
33; There are 64 stripes in the head of the large arrow. The 
333; calculation module divides the length of top edge by two 
333 each time it goes down another recursion level. By making 
333; the original top edge a multiple of 128, we maximize 
$33 continuity in striping between arrowheads and shafts and 
$33 among the first several levels of recursion. 
(defmethod (arrow-parameter-mixin :adjust-top-edge) () 
(setq top-edge 
3; Minimum length of top edge is 128 
(if (< top-edge 256) 128 
3; Otherwise set to next lower multiple of 128 
(* 128 (fix (// top-edge 128)))))) 


33; Calculates x-coordinate of top right point of figure. 
333 Finds horizontal length of figure by dividing length of 
333 top edge by 0.8. Centers the figure horizontally within 
3;; the page or window. 
(defmethod (arrow-parameter-mixin :compute-right-x) () 
(setq right-x 
(fixr (* 0.5 (+ width (// top-edge 0.8)))))) 
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333 Calculates y-coordinate of top right point of figure. 
33; Assumes that the origin is at bottom. Finds vertical 
333 length of figure by dividing length of top edge by 0.8. 
333; Centers the figure vertically within the page or window. 
(defmethod (arrow-parameter-mixin :compute-top-y) () 
(setq top-y 
(fixr (* 0.5 (+ height (// top-edge 0.8)))}))) 


333 Following are flavors and methods for screen output 


(defflavor basic-arrow-window-mixin 
(do-stripes max-dep fill-prop) 
() 

:initable-instance-variables 

(:required-flavors arrow-parameter-mixin tv:window) 

(:default-init-plist 

:edges-from ’:mouse :minimum-width 200 :minimum-height 200 

sblinker-p nil :expose-p t) 

(:documentation :mixin 

“Provides for a basic window to display the arrow graphic. 
ARROW-PARAMETER-MIXIN is needed to position the figure within 
the window. Instance variables hold values for maximum 
recursion level, proportion of window to be filled, and 
whether or not to stripe the figure. This flavor assumes 
window coordinates, with origin at top left. It provides its 
own :COMPUTE-TOP-Y method to use that origin. It provides a 
method to find the width and height of the window, as 
ARROW-PARAMETER-MIXIN requires. This flavor has a :SHOW-LINES 
method to receive point coordinates from the calculation 
module and draw lines on the window. It provides a :MAIN-LOOP 
method so that the window can run in its own process and let 
the user modify the graphic. TV:LIST-MOUSE-BUTTONS-MIXIN is 
needed to handle mouse clicks if this method is used. This 
flavor provides standard :AFTER daemons for the window-system 
:INIT, :REFRESH, and :CHANGE-OF-SIZE-OR-MARGINS messages. This 
flavor should be mixed in with ARROW-PARAMETER-MIXIN and 
TV:WINDOW for any window that produces the graphic. It 
should be included before ARROW-PARAMETER-MIXIN so that the 
:COMPUTE-TOP-Y method shadows correctly.")) 
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; Receives endpoint coordinates and draws lines on a window. 

; Arguments are alternating x- and y-coordinates of the end- 

; points of lines to be drawn. If there are more than two pairs 

; of coordinates, assumes that the endpoint of one line is the 

; starting point of the next. Sends messages for separate methods 


to determine the actual coordinates. This is so that other 


; flavors can modify the coordinates. Draws a line by sending self 


a :DRAW-LINE message, and so assumes that TV:GRAPHICS-MIXIN is 
included somewhere to provide this method. 


(defmethod (basic-arrow-window-mixin :show-lines) 


(x y &rest x-y-pairs) 


33; First determine the starting point of the line. On 
33 subsequent trips through the loop, the last endpoint 
3; becomes the next starting point. 


(loop for x0 


(send self *:compute-x x) then xl 
for yO = (send self ’:compute-y y) then yl 
3; “Cddr" down the list created by making all but the 
3; first pair of coordinates an &rest argument 
for (xl yl) on x-y-pairs by #’cddr 
3; Determine the endpoint of the line 
do (setq xl (send self °*:compute-x x1) 

yl (send self *:compute-y yl)) 
3; Draw the line 
(send self °:draw-line 

x0 yO xl yl tv:alu-ior t))) 


33; Determines the x-coordinate of an endpoint of a line. 
333; This is a separate method so that other flavors can shadow 


it or add daemons to manipulate the coordinate. 


(defmethod (basic-arrow-window-mixin :compute-x) (x) 
(fixr x)) 
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333 Determines the y-coordinate of an endpoint of a line. 
333 Assumes that the argument already uses window coordinates, 
333 with origin at top left. This is a separate method so that 
33; other flavors can shadow it or add daemons to manipulate 
333; the coordinate. 
(defmethod (basic-arrow-window-mixin :compute-y) (y) 

(fixr y)) 


333; Finds the inside width and height of the window. 
333 Sends self an :INSIDE-SIZE message, and so assumes that 
333 TV:MINIMUM-WINDOW is included somewhere to provide this 
333 method. 
(defmethod (basic-arrow-window-mixin 
scompute-width-and-height) () 
(multiple-value (width height) 
(send self °: inside-size))) 


33; Calculates y-coordinate of top right point of figure. 
333 Finds vertical length of the figure by dividing the length 
333; of top edge by 0.8. Centers the figure vertically within 
333 the window. Gives the result in window coordinates, with 
333 origin at top left. This method shadows that in 
333 ARROW-PARAMETER-MIXIN. 
(defmethod (basic-arrow-window-mixin :compute-top-y) () 
(setq top-y 
(fixr (* 0.5 (- height (// top-edge 0.8))}))) 


33; Calculates size and position of figure after initialization. 
3; Binds the global variable *fill-proportion® to the value of 
3; the corresponding instance variable so that the figure will 
3; be drawn correctly if the value of *fill-proportion® has 

3; changed. 
defmethod (basic-arrow-window-mixin :after :init) (ignore) 

(let ((*fill-proportion® fill-prop)) 

(send self °:compute-parameters))) 


( 


333; Calculates size and position of figure after window change. 
333; Binds the global variable *fill-proportion® to the value of 
333; the corresponding instance variable so that the figure will 
33; be drawn correctly if the value of *fill-proportion® has 
333 Changed. 
(defmethod (basic-arrow-window-mixin 
safter :change-of-size-or-margins) (&rest ignore) 
(let ((*fill-proportion® fill-prep)) 
(send self °:compute-parameters))) 
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33; Draws the figure when necessary after window is refreshed. 
333; Binds the global variable *dest*® to self and the variables 
333; *do-the-stripes® and *max-depth® to the corresponding instance 
333; variables so the figure will be drawn correctly if the values 
333; of the global variables have changed. 
(defmethod (basic-arrow-window-mixin :after :refresh 
(&optional type) 
3; Draw figure if not restored from a bit-save array ... 
(when (or (not tv:restored-bits-p) 
33... or size has changed ... 
(eq type °:size-changed) 
33. --- or new values for figure parameters. 
(eq type °:new-vals)) 
3; If restored from a bit-save array, clear screen first 
(when tv:restored-bits-p 
(send self °:clear-screen)) 
3; Bind global variables to self and instance variables 
(let ((*dest*® self) 
(*do-the-stripes® do-stripes) 
(*max-depth® max-dep) ) 
3; Draw the figure 
(draw-arrow-graphic top-edge right-x top-y)))) 


333 Provides a mouse documentation line for the window. 
33; The only option is to click right and pop up a 
33; choose-variable-values window of options for changing 
33; the graphic on this window. 
(defmethod (basic-arrow-window-mixin 
:who-line-documentation-string) () 
"R: Choose-variable-values options for changing figure on this window") 
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; Command lcop for window associated with a separate process. 
333; Consists of an error-restart-loop that handles restarts from 
; errors and sys:abort. Waits for mouse input. If a right 
333 Click, pops up a choose-variable-values window to change 
333; Characteristics of the figure. On exit, sets instance variables 
333 to the new values and refreshes the window, then waits for another 
$33 mouse click. Assumes blips are lists of the form provided 
$33 by TV: LIST-MOUSE-BUTTONS-MIXIN. 
(defmethod (basic-arrow-window-mixin :main-loop) () 
3; Run forever in a loop. Offer a restart handier if an error 
$3; or syS:abort is signalled. 
(error-restart-loop ((error sys:abort) “Arrow Window Top Level") 
3; Wait for input 
(let ((char (send self ’:any-tyi))) 
3; Pop up window if input is a list ... 
(when (and (listp char) 
$3 «.- and a mouse click ... 
(eq (first char) °:mouse-button) os 
$3. .-- and a single click on the right button. 
(eq (second char) #\mouse-r-1)) 
3; Bind global variables to instance-variable values 
(let ((*do-the-stripes*® do-stripes) 
(*max-depth* max-dep) 
(*fill-proportion® fill-prop)) 
3 Pop up a choose-var iable-values window 
(tv: choose-var iable-values 
*((*do-the-stripes® "Stripe the arrows?" :boolean) 
(*max-depth® "Number of recursicn levels" :number) 
(*fill-proportion® 
“Fraction of window to be filled” :number)) 
; Make the window wide to provide enough room for error 
3; messages. 
> sextra-width 20 
3; Call a function to check for errors when values change 
*:function *check-item 
3; Give the user a chance to abort 
*smargin-choices °("Do It" ("Abort" (signal *sys:abort))) 
*:label “Choose Options for Graphic") 
33; Set instance variables to the new values 
(setq do-stripes *do-the-stripes*® 
max-dep *max-depth* 
fill-prop *fill-proportion®) 
33 Recompute size and position of the figure 
(send self °:compute-parameters) 
3; Send :REFRESH message with argument of ’:new-vals to make 
33; sure the figure is redrawn if there is a bit-save array 
(send self *:refresh °’:new-vals)))))) 
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(defflavor basic-arrow-window () 
(basic-arrow-window-mixin 
arrow-parameter-mixin 
tv:any-tyi-mixin 
tv: list-mouse-buttons-mixin 
tv:process-mixin 
tv: window) 
(:documentation :combination 
"“Instantiable flavor providing a basic window for output. 
Though this flavor is instantiable, its methods assume that 
point coordinates use the window coordinate system, with 
origin at top left. To work with the current calculation 
module it needs another mixin to convert LGP to screen 
coordinates. In the component flavors, BASIC-ARROW-WINDOW-MIXIN 
must come before ARROW-PARAMETER-MIXIN and TV:WINDOW for 
shadowing and daemons to work correctly. TV:PROCESS-MIXIN 
and TV:LIST-MOUSE-BUTTONS-MIXIN are not necessary unless the 
window is associated with a separate process and the :MAIN-LOOP 
method of BASIC-ARROW-WINDOW-MIXIN is the command loop.")) 


(defflavor lIgp-window-mixin 
((scale-factor 2.5)) 
() 
(:required-flavors basic-arrow-window) 
(:documentation :mixin 
“Converts LGP to-screen coordinates and vice versa. 
When mixed in with BASIC-ARROW-WINDOW, this flavor allows 
window output with a calculation module that uses LGP 
coordinates. The instance variable SCALE-FACTOR is the 
ratio of LGP to screen pixel density. The methods take 
the height and width of the window in screen pixels and 
calculate the length of the top edge and the coordinates 
of the top right point of the figure in LGP pixels. In 
drawing lines on the window, the methods convert LGP to 
window coordinates. These methods shadow those in 
ARROW-PARAMETER-MIXIN and BASIC-ARROW-WINDOW-MIXIN.")) 


333; Converts x-coord of line endpoint from LGP to screen pixels. 
33; Corrects for higher density of LGP pixels. This method shadows 
33; that of BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (Igp-window-mixin :compute-x) (x) 

(fixr (// x scale-factor))) 


33; Converts y-coord of line endpoint from LGP to screen pixels. 
33; Corrects for higher density of LGP pixels and for screen origin 
333 at top left. This method shadows that of BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (Igp-window-mixin :compute-y) (y) 
(fixr (- height (// y scale-factor)))) 
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:3; Calculates top edge in LGP pixels from screen proportions. 
33; Multiplies length of smaller dimension, in screen pixels, by 
$33 proportion of this dimension to be filled by the figure. 
33; Multiplies this by 0.8 to find top edge in screen pixels. 
33; Corrects for higher density of LGP pixels. This method 
333; shadows that of ARROW-PARAMETER-MIXIN. 
(defmethod (igp-window-mixin :compute-top-edge) () 
(setq top-edge 
(fixr (* scale-factor 0.8 *fill-proportion® 
(min width height))))) 


33; Calculates x-coord of top right point in LGP pixels. 
333 Finds horizontal length of figure in screen pixels by 
33; dividing top edge by 0.8. Centers figure horizontally 
$33 in window, correcting for higher density of LGP pixels. 
333 This method shadows that of ARROW-PARAMETER-MIXIN. 
(defmethod (lgp-window-mixin :compute-right-x) () 
(setq right-x 
(fixr (* 0.5 (+ (* width scale-factor) 
(// top-edge 0.8)))))) 


333; Calculates y-coord of top right point in LGP pixels. 
333; Finds vertical length of figure in screen pixels by 
333; dividing top edge by 0.8. Centers figure vertically 
333; in window, correcting for higher density of LGP pixels. 
333 This method shadows those of ARROW-PARAMETER-MIXIN and 
333; BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (1gp-window-mixin :compute-top-y) () 
(setq top-y 
(fixr (* 0.5 (+ (* height scale-factor ) 
(// top-edge 0.8)))))) 


(defflavor arrow-window () 
(1gp-window-mixin basic-arrow-window) 

(:documentation :combination 

“Instantiable flavor for window output from LGP coordinates. 
This flavor has all the features of BASIC-ARROW-WINDOW but 
assumes that the calculation module uses LGP coordinates. This 
is the flavor to instantiate for window output using the 
current calculation module.")) 
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33; The following flavor and methods are for LGP output 


(defflavor lgp-pixel-mixin 
(output-stream) 
() 

:initable-instance-variables 

(:required-flavors arrow-parameter-mixin) 

(:documentation :mixin 

“Provides methods for arrow graphic output on an LGP stream. 
ARROW-PARAMETER-MIXIN is required to calculate the size of the 
figure and position it in the center of the page. This flavor 
has a method to calculate the width and height of the page, as 
ARROW-PARAMETER-MIXIN requires. It has a :SHOW-LINES method to 
receive point coordinates from the calculation module and draw 
lines on the output stream. The method assumes that coordinates 
are in LGP pixels. The method also assumes that flavor 
LGP:BASIC-LGP-STREAM is included in output stream to provide 
:SEND-COMMAND and :SEND-COORDINATES messages. This flavor 
should be mixed, along with ARROW-PARAMETER-MIXIN, into an 
instantiable flavor for LGP output. When that flavor is 
instantiated, the instance variable output-stream should be 
initialized.")) 


333; Receives endpoint coordinates and draws lines on LGP stream. 
33; Arguments are alternating x- and y-coordinates of endpoints of 
333; lines to be drawn. If there are more than two pairs of 
33; coordinates, assumes that the endpoint cf one line is the 
333; Starting point of the next. Draws a line by sending output 
$33 Stream :SEND-COMMAND messages for LGP commands and 
333; :SEND-COORDINATE messages for LGP coordinates. Assumes that 
333 flavor LGP:BASIC-LGP-STREAM is included in output stream to 
333; provide these methods. 
(defmethod (Igp-pixel-mixin :show-lines) 
(x0 yO &rest x-y-pairs) 
33; Send command and coordinates to start drawing lines 
(send self °:send-command-and-coordinates #/m x0 y0) 
3; "Cddr“ down the list created by making all but the first 
3; pair of coordinates an &rest argument 
(loop for (x y) on x-y-pairs by #’cddr 
3; Send command and coordinates to draw a line 
do (send self °*:send-command-and-coordinates #/v x y))) 


333; Sends line-drawing commands to LGP output stream. 

333 :SEND-COMMAND transmits an LGP command. :SEND-COORDINATES 

333 transmits coordinates of an endpoint of a line to be drawn. 
333; Assumes that LGP:BASIC-LGP-STREAM is included in output stream 
33; to provide these methods. 


(defmethod (1lgp-pixel-mixin :send-command-and-coordinates) (cmd x y) 


(send output-stream °*:send-command cmd) 
(send output-stream °:send-coordinates (fixr x) (fixr y))) 
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333 Finds width and height of a page for LGP output. 
333 This flavor is required by ARROW-PARAMETER-MIXIN. Finds the 
333 values of two instance variables of LGP:BASIC-LGP-STREAM: 
333 SI:PAGE-WIDTH and SI:PAGE-HEIGHT. Assumes that 
3; LGP:BASIC-LGP-STREAM is included in output stream to provide 
33; these instance variables. 
(defmethod (lgp-pixel-mixin :compute-width-and-height) () 
(setq width (symeval-in-instance output-stream °si:page-width) 
height (symeval-in-instance output-stream ’si:page-height) )) 


> 
° 
’ 


(defflavor lgp-pixel-stream () 
(igp-pixel-mixin arrow-parameter-mixin) 

(:documentation :combination 

“Instantiable flavor for arrow output on LGP stream. 
Assumes that the calculation module uses LGP coordinates. 
When this flavor is instantiated, the LGP-PIXEL-MIXIN 
instance variable OUTPUT-STREAM should be initialized. 
The output stream can be directed to an LGP or a file, 
but it must include flavor LGP:BASIC-LGP-STREAM for 
output to work correctly.")) 


3:3; Following are condition flavors for bad variable values 


(defflavor bad-arrow-variable () (error) 

(:documentation 

“Noninstantiable class of bad-variable conditions. 
The user might set some variables to impermissible values. 
These conditions are to permit checking for bad values 
beyond the system’s error checking. Instantiable condition 
flavors for specific variables should be built on this 
flavor .")) 


(defflavor bad-arrow-depth () (bad-arrow-variable) 
(:documentation 
“Proceedable condition: bad value for *MAX-DEPTH®. 
An instantiable condition flavor for impermissible values 
of *MAX-DEPTH*, the number of recursion levels in the 
figure.")) 


333 Prints string on stream to report bad *MAX-DEPTH*® value 
(defmethod (bad-arrow-depth :report) (stream) 
(format stream "No. of levels was not a ~ 
nonnegative fixnum.")) 
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:3; Proceed type method for supplying new value of *MAX-DEPTH* 
(defmethod (bad-arrow-depth :case :proceed :new-depth) 
(&optional (dep (prompt-and-read 
* snumber 
"Supply new value for ~ 
no. of recursion levels: “))) 
“Supply a new value for number of recursion levels." 
(values *’:new-depth dep)) 


(defflavor bad-arrow-fill-proportion () (bad-arrow-variable) 
(:documentation 
"Proceedable condition: bad value for *FILL-PROPORTION®. 
An instantiable condition flavor for impermissible values of 
*FILL-PROPORTION*®, the fraction of the smaller dimension of 
the page or window that the figure is to fill.")) 


333; Prints string on stream to report bad *FILL-PROPORTION® value. 
(defmethod (bad-arrow-fill-proportion :report) (stream) 
(format stream "Proportion was not a fraction between ~ 
0 and 1.")) 


$3; Proceed type method for new value of *FILL-PROPORTION® 
(defmethod (bad-arrow-fill-proportion :case :proceed 
snew-proportion) 
(&optional (prop (prompt-and-read 
*snumber 
"Supply new fraction of bounds ~ 
be filled: "))) 
"Supply a new fraction of page or window to be filled." 
(values °:new-proportion prop) ) 
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33; Top-level function 


333; Top-level function to call to produce arrow graphic. 
333 Pops up a choose-variable-values window to let user specify 
$33; output destination, number of recursion levels, proportion 
$33; of smaller dimension of page or window to be filled, and 
333 whether or not to stripe figure. If screen output, makes a 
333 window. If LGP output, makes an LGP stream and calls 
33; DRAW-ARROW-GRAPHIC to draw the figure. 
(defun do-arrow () 
3; Pop up a choose-variable-values window 
(tv: choose-var iable-values 
*((*do-the-stripes*® “Stripe the arrows?" :boolean) 
(*max-depth® “Number of recursion levels" :number) 
(*fi11-proportion*® 
“Fraction of page or window to be filled" :number) 
(*dest-string*® “Output destination" 
schoose ("Screen" "LGP" "File")) 
(*output-file*® “Pathname for file output" :pathname)) 
3; Make window wide enough to accommodate long pathnames 
33; and error messages 
*:extra-width 20. 
3; Call this function when a value is changed 
*:function *check-item 
3; Give user a chance to abort 
*smargin-choices °("Do It" ("Abort" (signal *sys:abort))) 
*;label “Choose Options for Graphic") 
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33; If figure is infinitely small, just return nil 
(cond ((= *fill-proportion® 0) nil) 
3; If screen output, make a window 
((equal *dest-string*® "Screen") 
(tv:make-window °arrow-window 
3; Initialize instance variables to 
33; values set by the user 
*:do-stripes *do-the-stripes* 
*smax-dep *max-depth* 
*:fill-prop *fill-proportion*® 
3; Specify top-level function for the 
33 process associated with the window 
*sprocess °(window- loop) )) 
3; If LGP or file output, use an appropriate stream 
(t (with-open-stream 
(stream 
3; This function returns a stream suitable for 
3; LGP output 
(si:make-hardcopy-stream 
3; Argument is the output device. For LGP, 
33; use the default hardcopy device. 
(if (equal *dest-string*® "Igp") 
si:*default-hardcopy-device* 
33; For file output, use the correct format 
3; for the hardcopy device and direct 
33; output to the file specified by the user 
(lgp:get-Ilgp-record-file-hardcopy-device 
*output-file*)))) 
3; Make an instance of our LGP output flavor 
(let ((*dest* 
(make-instance *lgp-pixel-stream 
s; Initialize instance 
3; variable to output stream 
> soutput-stream stream) )) 
33; Position the figure on the page 
(send *dest*® °*:compute-parameters) 
3; Draw the figure, using instance-variable values 
33; aS arguments 
(draw-arrow-graphic (send *dest*® °:top-edge) 
(send *dest*® °:right-x) 
(send *dest* *:top-y))))))) 


333 Top-level function for process associated with arrow window. 
333; The function is called when the window is created. Argument is 
333; the window. The function sends the window a :MAIN-LOOP message. 
333; This method should be the actual command loop for the process. 
(defun window-loop (window) 

(send window *:main-1loop) ) 
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333 Function to check variable values 


333 Called when a value changes in choose-variable-values window. 
333 Arguments are the window, the variable, and its old and new values. 
33; Binds handlers for conditions for impermissible values. If new 
33; value is OK, sets variable to the new value, refreshes window, and 
33; returns t. If value is not OK, signals the appropriate condition. 
33; When SIGNAL returns, presumably with a new variable value, checks 
33; the new value in the same way it checks a new value that comes 
33; from the window. 
defun check-item (cvv-window var old-val new-val) 
3; We don’t use the old value. To avoid a compiler complaint, 
33 just evaluate it and ignore it. We could also use IGNORE 
33; instead of OLD-VAL in the arglist, but then the arglist 
3; would be less meaningful. 
old-val 
3; Bind handlers for the conditions we might signal 
(condition-bind ({bad-arrow-depth °bad-arrow-var-handler ) 
(bad-arrow-fill-proportion 
*bad-arrow-var-handler ) ) 
(when (eq var °*max-depth*) 
33; *MAX-DEPTH® must be nonnegative fixnum 
(loop until (and (fixp new-val) (2 new-val 0)) 
3; If it’s not, bind QUERY-IO to the window and 
3; Signal a condition. SIGNAL should return 
3; two values, the proceed type and the new 
3; value from the proceed method. Ignore the 
3; proceed type and set NEW-VAL to the new 
33 value. 
do (let ((query-io cvv-window) ) 
(multiple-value (nil new-val) 
(signal *bad-arrow-depth))))) 
(when (eq var °*fill-proportion®) 
33; *FILL-PROPORTION® must be between 0 and 1 
(loop unti} (and (2 new-val 0) (¢ new-val 1)) 
3; If it’s not, bind QUERY-IO to the window and 
33 signal a condition. SIGNAL should return 
3; two values, the proceed type and the new 
3; value from the proceed method. Ignore the 
33; proceed type and set NEW-VAL to the new 
33 value. 
do (let ((query-io cvv-window) ) 
(multiple-value (nil new-val) 
(signal *bad-arrow-fill-proportion))))) 
3; Variable value is now OK. Set variable to the new value. 
3; Note that we DO want to evaluate VAR. 
(set var new-val) 
3; Refresh the window 
(send cvv-window °:refresh) 
3; Return t 


t)) 
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33; Handler for bad-variable-value conditions 


33; Handler for bad value of *MAX-DEPTH* or *FILL-PROPORTION®. 
333; Argument is the condition object created by SIGNAL. Uses QUERY-IO 
3:3 Stream to report condition. Sends the condition object a :PROCEED 
333 Message and passes back the values it returns. 
(defun bad-arrow-var-handler (cond-obj &aux b1) 
~ 33 Find out whether this object has the right proceed type. 
3; If not, return nil. 
(if (send cond-obj ’°:proceed-type-p 
(cond ((typep cond-obj ’bad-arrow-depth) °:new-depth) 
((typep cond-obj *bad-arrow-fiil-proportion) 
*:new-proportion) )) 
3; Enclose the handling operation in an UNWIND-PROTECT so that 
33; if we use a blinker we are sure to turn it off 
(unwind-protect 
(progn 
3; Use a blinker if the QUERY-IO stream is a window 
(setq bl (if (typep query-io ’tv:sheet) 
3; If a cursor-following blinker exists, use it 
(or (tv:sheet-following-blinker query-io) 
3; Otherwise, makes a new blinker 
(tv:make-blinker query-io 
*tv:rectangu lar-bl inker 
*:follow-p t)))) 
33; If a blinker, make it blink 
(if bi (send bl °:set-visibility °:blink)) 
3; Alert the user 
(tv: beep) 
3; Send a report, presumably describing the condition 
(send cond-obj *:report query-io) 
3; Send object a :PROCEED message and return the values 
3; that the method returns 
(send cond-obj ’:proceed 
(cond ((typep cond-obj ’bad-arrow-depth) °:new-depth) 
((typep cond-obj *bad-arrow-fill-proportion) 
*:new-proportion)))) 
33; If a blinker, turn it off 
(if bl (send bl °:set-visibility nil))))) 


33; This macro expression causes combined methods to be compiled at 

333 compile time and data structures to be generated at load time. 

33; Otherwise, these things happen at run time, when the first 

333 instance of a flavor is made. 

(compile-flavor-methods arrow-window lIgp-pixel-stream 
bad-arrow-depth bad-arrow-fill-proportion) 
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LINE (Indent New Line) 21 
Lisp input editing 68 
Lisp input editor commands 
c-C 69 
m-C 69 
Lisp Mode (m-x) 10 
List Callers (m-x) 31, 37 
List Changed Definitions (m-x) 49 
List Changed Definitions Of Buffer (m-x) 49 
List Combined Methods (m-x) 131 
List Matching Lines (m-x) 50 
List Matching Symbols (m-x) 32 
List Methods (m-x) 130 
list-mouse-buttons-mixin, Flavor (in package tv:) 118 
listarray, Function 30 
Load Compiler Warnings (m-x) 73 
Load File {m-x) 66 
load, Function 66 
Long Documentation (m-sh-D) 32, 36 


m-% (Query Replace) 5i 
m-. (Edit Definition) 33, 128, 129 
m-; (Indent For Comment) 20 
m-8 (Debugger command) 75 
m-C (Lisp input editor command) 69 
m-ESCAPE (Evaluate Minibuffer) 68 
m-L (Debugger command) 75 
m-LINE (Indent New Comment Line) 20 
m-N (Down Comment Line) 20 
m-P (Up Comment Line) 20 
m-sh-C (Compile Changed Definitions Of Buffer) 64 
m-sh-0 (Long Documentation) 32, 36 
m-sh-E (Evaluate Changed Definitions Of Buffer) 68 
m-SPACE (Push Pop Point Explicit) 52 
m-W (Save Region) 54 
m-Y (Yank Pop) 54 
Macro Expand Expression (c-sh-m) 94 
Macro Expand Expression All (m-x) 94 
Macros 
compile-flavor-methods 128 
condition-bind 123 
defconst 62 
defflavor 103, 106 
defsystem 51 
defvar 13, 62 
defwindow-resource 115 
error-restart-loop 119 
Expanding 91 
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Keyboard 56 
with-open-stream 116 
make-blinker, Function (in package tv:) 127 
make-hardcopy-stream, Function (in package si:) 116 
make-system, Function 71 
make-system Options 
tbatch 71 
make-window, Function (in package tv:) 102, 112, 115, 
118 
Mark Definition (c-m-H) 54 
Mark Whole (c-x H) 56 
Menu items 
[ARGPDL] 86 
[Attributes] 128 
[Break after] 86 
[Break before] 86 
[Cond after] 86 
[Cond before] 86 
[Cond break after] 86, 91 
[Cond break before] 86, 91 
[Conditional] 86 
[Edit Screen] 58, 121 
{Edit] 7, 74 
{Error] 86, 90 
[Exit] 94 
[Inspect] 97 
[Modify] 95 
[Print after] 86 
[Print before] 86 
[Print] 86 
[Retry] 74 
[Return] 94, 95 
[Split Screen] 58, 121 
[Step] 86, 89 
[Trace] 85,89 
[Untrace] 86 
[Wherein] 86 
Method combination 
scase 122 
sdaemon 103, 106, 108, 109, 110, 111 
Methods 129 
sany-tyi for tv:any-tyi-mixin 119 
:change-of-size-or-margins for tv:sheet 109 
Daemon 108, 109 
:draw-line for tv:graphics-mixin 11, 106 
sinit for tv:sheet 109 
sinside-size for tv:minimum-window 107 
:operation-handled-p for si:vanilla-flavor 131 
Primary 103, 108, 110 
sproceed 122, 123, 126 
refresh for tv:sheet 109, 120 
‘report 122, 126 
:send-command for lgp:basic-lgp-stream 113 
:send-coordinates for lgp:basic-lgp-stream 113 
:which-operations for si:vanilla-flavor 131 
:who-line-documentation-string 119 
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mexp, Function 94 
Minibuffer 6 


sminimum-height, Init Option to tv:minimum-window 


106 


Packages 7, 8, 17, 31, 36 
Parentheses, Balancing 21 
Pathnames 37 


¢minimum-width, Init Option to tv:minimum-window 106 pkg-goto, Function 17 


minimum-window, Flavor (in package tv:) 107 
Modes 9 
Modified Two Windows (c-x 4) 57 
[Modify] 95 
Modularity 103 
Mouse clicks 118 
Mouse documentation string 119 
Move To Previous Point (c-m-SPACE) 52 
Moving text 51 
Multiple 

Buffers 57 

Windows 57 
Multiple Edit Callers (m-x)} 37 
Multiple List Callers (m-x) 37 
multiple-value, Special Form 107 


Name Last Kbd Macro (m-x) 56 
nil, Option to trace 87 


Objects 28 
One Window (c-x 1) 57 
Open Get Register (c-x 6} 55 


soperation-handled-p, Method for si:vanilla-flavor 131 


Options 
sargtotrace 87 
:argpdl to trace 87 
sbatch to make-system 71! 
sboth to trace 87 
:break to trace 87, 91 
:cond to trace 87 
:default-init-plist to defflavor 106 
:documentation to defflavor 129 
sentry to trace 87 
sentrycond to trace 87 
sentryprint to trace 87 
:error to trace 87, 91 
sexit to trace 87 
:exitbreak to trace 87, 91 
:exitcond to trace 87 
:exitprint to trace 87 
:function to tv:choose-variable-values 121 
:gettable-instance-variables to defflavor 103 


sinitable-instance-variables to defflavor 112, 115 


mil to trace 87 

tprint to trace 87 
srequired-flavors to defflavor 106 
:required-methods to defflavor 103 
sstep to trace 87, 89 


plist, Function 32 

Primary methods 103, 108, 110 

[Print] 87 

[Print after] 87 

[Print before] 87 

Print Modifications (m-x) 50 

sprint, Option to trace 87 

sproceed, Method 122, 123, 126 

Proceed types 74, 122 

Proceeding 122 

sprocess, Init Option to tv:process-mixin 118 
process-mixin, Flavor (in package tv:) 118 
Processes 118, 119 

prompt-and-read, Function 126 

Push Pop Point Explicit (m-space) 52 

Put Register (c-x x) 55 


Query Replace (m-%) 51 
query-ic, Variable 126, 127 
Quick Arglist (c-sh-A) 36 
bia: {c-Z) 74 


eietvee: Method for tv:sheet 109, 120 
Registers 55 

Reparse Attribute List (m-x) 9 

Replace (c-z) 51 

Replacing 50 

treport, Method 122, 126 
srequired-flavors, Option to defflavor 106 
srequired-methods, Option to defflavor 103 
Resources 115 

Restart handlers 74 

RESUME 68, 89 

[Retry] 74 

RETURN 6 

[Return] 94, 95 

Reverse Search (c-r) 51 


Save Position (c-x $) 52 

Save Region (m-w) 54 

Scroll Other Window (c-m-v) 57 
Searching 50 

Select All Buffers As Tag Table {m-x) 51 
Select Buffer (c-x 8) 52 

SELECTE 7 

SELECT 1 97 

Select Previous Buffer (c-m-L) 52 

Select System As Tag Table (m-x). 51 


ssend-command, Method for Igp:basic-lgp-stream 113 
ssend-coordinates, Method for Igp:basic-lgp-stream 113 
Set Backspace (m-x) 9 


svalue to trace 87 
swherein to trace 87 
Other Window (c-x 0) 57 
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Set Base (m-x) 9 Tags Search (m-x} 51 
Set Comment Column (c-x ;) 21 Tags tables 50 
Set Fill Column (c-x F) 10 terminzal-io, Variable 11, 101 
Set Fonts (m-x) 9 Text 
Set Key (m-x) 56 Killing 52 
Set Lowercase (m-x) 9 Moving 51 
Set Nofill (m-x) 9 Yanking 52 
Set Package (m-x) 9 [Trace] 85, 89 
Set Patch File (m-x) 9 Trace (m-x) 85, 89 
Set Pop Mark (c-SPACE) 52 trace Options 
Set Tab Width (m-x) 9 sarg 87 
Set Vsp (m-x) 9 sargpdl 87 
sheet, Flavor (in package tv:) 127 sboth 87 
sheet-following-blinker, Function (in package tv:) 127 tbreak 87, 91 
si:flavor-allowed-init-keywords, Function 131 scoud 87 
si:make-hardcopy-stream, Function 116 ceniry 87 
Si:vanilla-flavor, Flavor 129 sentrycond 87 
si:vanilla-flavor Methods sentryprint 87 
soperation-handled-p 131 . serror 87, 91 
swhich-operations 131! sexit 87 
signal, Function 102, 123, 126 sexitbreak 87, 91 
Signalling conditions 121 zexitcond 87 
Source Compare (m-x) 50 cexitprint 87 
Source Compare Merge (m-x) 50 snil 87 
SPACE 6 sprint 87 
SPACE (Stepper command) 86 step 87,89 
Special commands (Debugger) 74 svalue 87 
Special Forms :wherein 87 
break 90 trace, Special Form 86, 89, 91 
multiple-value 107 Tracing 84 
trace 86, 89, 91 tv:any-tyi-mixin, Flavor 118 
untrace 86, 87 tv:any-tyi-mixin Methods 
unwind-protect 127 sany-tyi 119 
[Split Screen] 58, 121 tv:choose-variable-values, Function 114, 121 
Split Screen (m-x) 57 tv:choose-variable-values Options 
standard-cutput, Variable 66 ‘function 121 
Start Kbd Macro (c-x () 56 tv:graphics-mixin, Flavor 106 
{Step] 87, 89 tv:graphics-mixin Methods 
step, Function 89 :draw-line 11, 106 
step, Option to trace 87, 89 tv:list-mouse-buttons-mixin Flavor 118 
Stepper 86 tv:make-blinker, Function 127 
Stepper commands tv:make-window, Function 102, 112, 115, 118 
c-B 88 tv:minimum-window, Flavor 107 
c-E 88 tv:misimum-window Init Options 
c-N 86 sblinker-p 106. 
c-U 88 sedges-from 106 
c-X 88 sexpose-p 106 
SPACE 86 sminimum-height 106 
Stepping 66, 86 sminimum-width 106 
SUSPEND 68 tv:minimum-window Methods 
Swap Point And Mark (c-x ¢-x) 52 tiuside-size 107 
Symbols 30 tv:process-mixin, Flavor 118 
sys:abort, Flavor 119 tv:process-mixin Init Options 
sprocess 118 
TaB (Indent For Lisp) 21 tv:sheet, Flavor 127 


Tags Query Replace (m-x) 51 tv:sheet Methods 
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:change-of-size-or-margins 109 

tinit 109 ; 

trefresh 109, 120 
tv:skeet-following-blinker, Function 127 
tv:window, Flavor 102, 105, 106, 107 
Two Windows (c-x 2) 57 
typep, Function 129 


unbreakon, Function 90 
{Untrace] 87 

untrace, Special Form 86, 87 
unwind-protect, Special Form 127 
Up Comment Line (m-P) 20 
Update Attribute List (m-x) 9 


:value, Option to trace 87 
values, Variable 89 
vanilla-flavor, Flavor (in package si:) 129 
Variables 32 
arglist 89 
query-io 126, 127 
standard-output 66 
terminal-io 11, 101 
values 89 
View Directory (m-x) 38 
View Two Windows (c-x 3) 57 


what-files-call, Function 32 
Where Is Symbol (m-x) 31 
where-is, Function 31! 
{Wherein] 87 
:wherein, Option to trace 87 
:which-operations, Method for si:vanilla-flavor 131 
who-calls, Function 32 
:who-line-documentation-string, Method 119 
Whoppers 108 
window, Flavor (in package tv:) 102, 105, 106, 107 
Windows 

Choose variable values 114, 119 

Multiple 57 
with-open-stream, Macro 116 


Yank (c-Y) 54 
Yank Pop (m-Y) 54 
Yanking text 52 
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Program Development Help Facilities 


The Lisp Machine software development environment contains many help facilities. This 
document summarizes the facilities for finding out information about the program you are writing 
and about the general state of your Lisp environment. 


This is not a document about program development and not a document about help facilities in 
general. It is a collection of the support tools and facilities available for finding the kind of 
information that you need while programming. It is not exhaustive but suggestive. It does not 
recommend strategies for applying these facilities but rather lays out what is available for creating 
a personal style of using the Lisp Machine effectively. 


The document contains three parts. The first part explains some interaction conventions for name 
completion and using the mouse to find information. The second part contains a summary by 
topic of Zmacs and Lisp functions that provide information or assistance during programming. 
The third part is an alphabetical reference listing of the functions that appear in the summary list. 


This document is related to several other documents: 


Lisp Machine Summary 
Lisp Machine Manual 
Zmacs Manual 


Refer to these other documents for related information and explanations of terminology. 


Interaction Conventions 


The Lisp Machine software has some general interaction conventions. For example, many editor © 
commands offer name completion. You can apply these facilities to exploring the command space 
of the machine. This section describes some general facilities and strategies for making more 
effective use of the machine. 


Mouse documentation line 


The mouse documentation line contains information about what different mouse clicks mean. As 
you move the mouse across different mouse-sensitive areas of the screen, the mouse documentation 
line changes to reflect the changing commands available. 


When no documentation appears, it does not necessarily mean that the mouse clicks are 
undefined. Not all programs have provided material for the mouse documentation line. When 
the mouse documentation line is blank at "top level" in a window, the mouse usually offers some 
standard commands. mouse-L selects a window; mouse-R brings up either the system menu or a 
menu specific to the application. 


7 


Zmacs Completion 


Zmacs minibuffer commands offer completion over various name spaces. Completion is a facility 
for reducing the number of keys you need to type to specify a name. As-soon as you have typed 
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enough characters for a name to be recognized as unique, you can ask for completion. Up until 
then, you can ask to see which names are possible completions of what you have typed. You can 
tell when completion is available; the notation "(Completion)" appears at the right end of the 
minibuffer label line. 


Completion for extended commands (m—X commands) 


The following table summarizes the keys that control completion for entering extended commands. 


Key Action in m-X commands 

SPACE Completes the words up to the current word, as far as they are unique. 
HELP or c-? Shows the possible completions in the typeout area. 

mouse-R Pops up a menu of the possible completions. 

c-/ Runs Apropos for each of the partially typed words in the name. 


AL TMODE Displays the full command name, if possible. 
RETURN, END Confirms the command when possible, whether or not you have seen its full name. 


Request completion by typing either ALTMODE or RETURN. Using ALTMODE shows the completed 
name, requiring a further RETURN to confirm it; using RETURN gets you completion and 
confirmation in one step. 


Any time you are typing in a Zmacs extended command name, completion is available. Zmacs 
command name completion works on initial substrings of each word in the command. For 
example, "m-X e z" is enough to specify the extended command "Edit Zmacs Command". 


Until Zmacs can recognize the name as unique, your request for completion just completes as far 
as possible. Using ALTMODE at this point moves the input cursor to the first ambiguous place in 
the command name. 


Whenever you are entering a name in a minibuffer that offers completion, you can find out all 
possible completions of what you have typed so far. Two styles are possible. Using HELP or c-? 
shows the list of completions in the typeout area; the names are mouse-sensitive. Using mouse-R 
shows the list in a pop-up menu. One good strategy for browsing is to look at the list of 
completions for initial substrings that are common command verbs, like "list" or "set". 


Completion for m—. 


The m-. (Edit Definition) command offers completion over the set of names that is in the files 
that have already been loaded into editor buffers. In this case, you request completion with 
ALTMODE and then confirm it with RETURN. 


m-. offers initial substring name completion, with hyphens rather than spaces delimiting the 
words. For example, "e-d-i" would be sufficient for specifying edit-definition-internal 
(assuming that Zmacs had previously parsed the source file containing it into a buffer). 


Completion in other contexts 


Completion is available in several other contexts, for example, buffer names and package names. 
We are gradually extending the contexts in which completion is available. Be on the lookout for 
the presence of "(Completion)" in the minibuffer label line. The conventions for extended 
commands usually apply. 
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Typeout windows in Zmacs 


Most of the Zmacs commands for looking up information display the information in a typeout 
window. A typeout window overlays the current buffer display with its contents and disappears as 
soon as you type any character. Most typeout windows contain mouse-sensitive items. In 
particular, Zmacs commands and Lisp function specs are mouse-sensitive and small menus of 
operations on the names are available (Arglist, Edit Definition, and so on). See the mouse 
documentation line. 


HELP keyin any Zmacs editing window 


The HELP key enables you to locate help material that is relevant to the current context. 
Individual programs are responsible for providing the routines that support the HELP key. The 
most complex general help facility is that provided by Zmacs editing windows. The HELP key 
provides access to a number of distinct kinds of help, depending on the key you press after the 
HELP key. 


Command Description 

HELP ? Displays a brief summary of the Zmacs help options (rather like the rest of this 
chart). 

HELP A For looking up all Zmacs commands whose names contain a specified substring. 


You type the substring. Zmacs displays the one-line documentation for the 
command and which key invokes it in the current context, if any. See HELP V 
for looking up variable names. The "A" stands for "apropos". When people say, 
"Use Apropos," they are referring to this function. 


HELP C For looking up which command is bound to a particular key. You type the key; 
Zmacs displays the name of the command and its summary paragraph. HELP C 
uses Self Document. 


HELP D For looking up the summary paragraph for a Zmacs command. You enter the 
command name. Completion is available. It does not tell you how to invoke a 
command. Use HELP W for that. HELP D uses Describe Command. 


HELP L For finding out what you did that caused unexpected behavior. Zmacs displays a 
representation of the last 60 keys that you pressed. HELP L uses What Lossage. 


HELP U For undoing the last major operation. Zmacs preserves a copy of the buffer 
before doing certain operations, in particular, sorting and filling. You can revert 
to the state prior to one of those kinds of operations by using HELP U. Zmacs 
queries you whether to go ahead with undoing; the only information you have 
about what is being undone is the name of the class of operation, for example, 
"fill" or "sort". HELP U uses Undo. 


HELP V For looking up all Zmacs user variables whose print names contain a specified 
substring. You type the substring. Zmacs displays the variable names and their 
current values. See HELP A for looking up command names. HELP ¥ uses 
Variable Apropos. 


HELP W For finding the key assignment for a particular command. You type the 
command name; Zmacs displays the current key assignment. Completion is 
available. HELP W uses Where Is. 
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Notation Conventions 


The keys with black lettering (like SHIFT or META) are shift keys, designed to be pressed in 
combination with other keys. They do not themselves transmit characters. Their combinations 
are shown hyphenated to remind you to press them at the same time as the associated key, not 
before. 


The keys with white lettering (like X or SYSTEM) all transmit a character. Combinations of these 
keys are meant to be pressed in sequence, for example, SYSTEM L means to press the SYSTEM key, 
release it, and then press the L key. 


The CTRL and META key combinations are abbreviated with c- and m-; the SUPER, HYPER, and 
SHIFT keys with s-, h-, and sh-, respectively. For example, the combined key press META-X is 
pronounced "meta x" and written as "m-X". 

This document uses the following notation conventions: 


Appearance in document Representing 

send, chaos:host-up Printed representation of Lisp objects in running text. 

RETURN, ABORT, c-F Keyboard keys. 

SPRCE Space bar. 

— login Literal type-in. 

(make-symbol "foo") Lisp code examples. 

function name arg! arg2 Syntax descriptions of definitions. 

Undo, Tree Edit Any Command names in Zmacs and Zmail appear with initial letter of 
each word capitalized. 

Insert File (m-X) Extended command names in Zmacs and Zmail. Use m-X to invoke 
one. 

[Map Over] Menu items. 

(mouse-R) Mouse clicks; L=left, M=middle, R=right. 


Mouse commands use notations for menu items and mouse clicks in the following ways: 


Square brackets delimit a mouse command; slashes (/) separate the members of a compound 
mouse command. The notation indicates which button to click only when that differs from the 
standard. For a single menu item, always click left. For example, the following two commands 
are exactly the same: 


[Previous] 
[(mouse-L) Previous] 


For a compound command, always click right on each menu item except the last, where you click 
left. For example, the following two compound commands are exactly the same: 


[Map Over / Move / Hardcopy] 
[(mouse-R) Map Over / (mouse-R) Move / (mouse-L) Hardcopy] 


For all other cases, the notation shows explicitly which button to click. For example: 
[Map Over / (mouse-M) Move] 
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Some more examples: 


- Suppose you are to click right on menu item [Map Over], then click right on menu 
item [Move], then click left on menu item [Hardcopy]. The notation is: 
[Map Over / Move / Hardcopy] 


- Suppose you are to click left on menu item [Previous]. The notation is: 
[Previous] 


- Suppose you are to click right on menu item [Map Over], then click middle on menu 
item [Move]. The notation is: 
[Map Over / (mouse-M) Move] 


- Suppose you are to click right on menu item [Previous]. The notation is: 
[(mouse-R) Previous] 


In this document, all Zmacs commands appear by name rather than by key binding. Command 
tables indicate whether the command has a standard key binding or whether it must be used as 
an extended command. For example, Edit Zmacs Command is an extended command and 
requires that you invoke it with m-X. Forward Word is bound to the m-F key; you invoke it by 
pressing the key. 


Command Type of command 

Edit Zmacs Command (m-%) An extended command 

Forward Word (m-F) A command with a standard key binding 
Find File (c-X c-F) A command with a standard key binding 


Functions and their arguments appear in the following kind of summary line: 


(apropos string package inferiors superiors) 
Words in italics are the arguments to the function. The words reflect the meaning of the 
argument. Underlined words are optional arguments; you can leave them out. The reference 
description for the function explains the meanings of the arguments and the default values for 
optional arguments. 
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Summary of Functions in Different Contexts 


Both Zmacs and Lisp offer facilities for finding information either about themselves or about the 
current environment. In addition, Zmacs offers ways to find information about Lisp functions 
and variables. 


This section lists the names of the functions and commands that are available, grouped according 
to the context in which they are available. The purpose of this section is to summarize the 
capabilities and to help you determine both the overall contexts for which you can find help and 
a particular function that might be what you are looking for. Explanations for each of these 
functions appear in an alphabetical listing in the third part of this document. 


Zmacs commands for finding out about the state of buffers 


Edit Buffers (m-X) . 

Edit Changed Definitions (m—-X) 

Edit Changed Definitions Of Buffer (m-x) 
List Buffers (c-X c-B) 

List Changed Definitions (m-%) 

List Changed Definitions Of Buffer (m—) 
List Definitions (m-X) 

List Matching Lines (m-) 

Print Modifications (m-%) 

Select System as Tag Table (m-%) 

Tags Search (m-X) 


Zmacs commands for finding out about the state of Zmacs 


Apropos (HELP A, m-%) 
Describe Variable (m—%) 

Edit Zmacs Command (m-X) 
List Commands (m-X) 

List Registers (m—-) 

List Some Word Abbrevs (m-X) 
List Tag Tables (m-X) 

List Variables (m-X) 

List Word Abbrevs (m—-%) 


Zmacs commands for finding out about Lisp 


Brief Documentation (c-sh-D) 
Describe Variable At Point (c-sh-¥V) 
Edit Callers (mx) 

Edit Definition (m-.) 

Edit File Warnings (m-X) 

Function Apropos (tm-) 

List Callers (m-%) 

List Matching Symbols (m—-%) 

Long Documentation (m-sh-D) 
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Multiple Edit Callers (m-) 
Multiple List Callers (m—X) 
Quick Arglist (c-sh-A) 
Where Is Symbol (m-X) 


Zmacs commands for finding out about flavors 


Describe Flavor (m—-X) 

Edit Combined Methods (m-%) 
Edit Methods (m-x) 

List Combined Methods (m-) 
List Methods (m-%) 


Zmacs commands for interacting with Lisp 


Break (BREAK) 

Compile And Exit (m-2) 

Compile Buffer (m-X) 

Compile Changed Definitions (m-X) 
Compile Changed Definitions Of Buffer (m—sh-C, m-X) 
Compile File (m-%) 

Compile Region (c-sh-C, m-%) 

Compiler Warnings (m-X) 

Edit Compiler Warnings (m-X) 

Evaluate And Exit (c-m-2) 

Evaluate And Replace Into Buffer (m-%) 
Evaluate Buffer (m-X) 

Evaluate Changed Definitions (m-) 
Evaluate Changed Definitions Of Buffer (n-sh-E, m-X) 
Evaluate Into Buffer (m-X) 

Evaluate Minibuffer (m-ALTMODE) 
Evaluate Region (c-sh-E, m-) 

Evaluate Region Hack (m-X) 

Evaluate Region Verbose (c-m-sh-E) 
Load Compiler Warnings (m-X) 

Macro Expand Expression (e-sh-M, m-%) 
Trace (m-%) 

Quit (c-z2) 


Lisp facilities for finding out about Lisp 


(apropos string package inferiors superiors) 
(arglist function flag) 

(describe objec) 

(describe-area area-name) 
-(describe-defstruct instance structure-name) 
(describe-flavor f/avor-name) 
(describe-package package-name) 
(describe-system system-name) 
(disassemble function) 

(documentation function) 
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(si:flavor-allowed-init-keywords flavor-name) 
(inspect object) 
(compiler:load-compiler-warnings file flush-flag) 
(mexp) 

(trace specs) 

(untrace specs) 


(variable-boundp variable) 

(what-files-call string package) 

(where-is symbol package) . 
(who-calls symbol package inferiors superiors) 
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Reference Description of Functions 


This section contains a summary paragraph of documentation for each of the information-finding 
commands and functions appearing in the summary lists of this document. 


This reference list is in alphabetical order by name of the command or function. Zmacs editor 
commands appear according to the names of the commands that implement them, rather than 
according to the names of the keys that invoke them. For example, m-X Compile Buffer appears 
under "C" rather than under "M"; c-sh-A appears under "Q" (because its name is Quick Arglist) 
rather than under "C". For commands that are usually invoked by a single key rather than by 
m-X, the key name appears with the command. (Remember you can always use HELP W to find a 
key name.) 


Some Zmacs commands come in pairs, for example, List Callers and Edit Callers. The commands 
are very similar. The List version allows you to just look at the list or to decide to start editing 
the items in the list. The list items are always mouse-sensitive. For the Edit version of the 
command, c-. is always the command for moving to the next item. 


Apropos (HELP A, m—-%) 
Displays all the Zmacs commands whose names contain a specified substring. 
You type the substring. Zmacs displays one line of documentation for the 
command and which key invokes it in the current context, if any. 


(apropos string package inferiors superiors) 
Displays all of the symbols whose print names contain the string. By default, it 


looks in the global package and its descendants, but you can specify a package 
name. For symbols that have function bindings, it displays the argument list. 
For symbols that are bound, it displays a notation "Bound". apropos returns 
the list of symbols that it found. 

(apropos "forward" *zwei) 

(apropos "process" *global nil) 


The second example looks only in the global package, not in any of its 
inferiors. 


(arglist function flag) (see also Quick Arglist) 
Returns a representation of the arguments that the function expects. When the 
original function definition contained an arglist declaration, arglist returns 
that list when flag is not specified or nil. When flag is not nil, then arglist 
returns the real argument list from the function. When the original function 
used a values declaration, arglist returns the names for the values returned by 
the function. . 

(arglist *make-array) 


You cannot use arglist to find the arguments for combined methods. 


BREAK Enters a Lisp Listener from the current window. It uses the screen area of the 
| frame that was selected when you used BREAK. When you use it from the 
editor, any Lisp forms you type are evaluated in the current package (the one 
showing in the status line). Use RESUME to return to the original context. 


Brief Documentation (c-sh-D) (see also Long Documentation) 
Displays brief documentation for the specified Lisp function. By default, it 
displays documentation for the current function. With a numeric argument, it 
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prompts for a function name, which you can either type in or select with the 
mouse. It displays the first line from the summary paragraph in the echo area. 


e-m-sh-E See Evaluate Region Verbose. 
c-sh-A See Quick Arglist. 

e-sh-C - See Compile Region. 

e-sh-D See Brief Documentation. 
e-sh-E See Evaluate Region. 

ce-sh-V See Describe Variable At Point. 


Compile And Exit (m-2) 
Compiles the buffer and returns from top level. It selects the window from 
which the last (ed) function or the last debugger c-E command was executed. 


Compile Buffer (m-x) 
Compiles the entire buffer. With a numeric argument, it compiles from point 
to the end of the buffer. (This is useful for resuming compilation after a prior 
Compile Buffer has failed.) 


Compile Changed Definitions (m-) 
Compiles any definitions that have changed in any Lisp mode buffers. With a 
numeric argument, it queries individually about whether to compile eac. 
changed definition. 


Compile Changed Definitions Of Buffer (m-sh-C, m-X) 
Compiles any definitions in the current buffer that have been changed. With a 
numeric argument, it prompts individually about whether to compile each 
changed definition. 


Compile File (m—-%) 
Compiles a file, offering to save it first. It prompts for a file name in the 
minibuffer, using the file associated with the current buffer as the default. It 
offers to save the file if the buffer has been modified. 


Compile Region (c-sh-C, m-%) 
Compiles the region, or if no region is defined, the current definition. 


Compiler Warnings (m-X) (see also Edit Compiler Warnings) 
Puts all pending compiler warnings in a buffer and selects that buffer. It loads 
the compiler warnings database into a buffer called *Compiler-Warnings-1*, 
creating that buffer if it does not exist. 


(describe object) (see also inspect) 
Displays available information about an object, in a format that depends on the 
type of the object. For example, describing a symbol displays its value, 
definition, and properties. describe returns the object. 
(describe ’time:get-time) 


(describe-area area-name) 
Displays attributes of the specified area. 
(describe-area (%area-number ’foo)) 
(describe-area ’working-storage-area) 


(describe-defstruct instance structure-name) 
Displays a description of the instance, showing the contents of each of its slots. 
structure-name is not necessary for named structures but must be provided for 
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unnamed structures. When you use supply structure-name, you force the 
function to use that structure name instead of letting the system figure it out; 
in addition, it overrides the :describe option for structures that know how to 
describe themselves. 


Describe Flavor (m-%) (see also describe-flavor) 
Displays a description of a flavor. It reads a flavor name via the mouse or 
from the minibuffer using completion. It displays a description of the flavor in 
a typeout window. The description includes names of flavors that the specified 
one directly depends on and names of flavors that depend on it. It also 
displays the documentation and the names of its instance variables. 


(describe-flavor flavor-name) (see also Describe Flavor) 
Displays descriptive information about a flavor. 
(describe-flavor *tv:basic-menu) 


Saat package package-name) 
Displays information about a package. 
(describe-package ’zwei) 


That example is the same as this one: 
(describe (pkg-find-package *zwei)) 


(describe-system system-name) 
Displays information about a system, including the name of the file containing 
the system declaration and when the files in the current version of the system — 
were compiled. 


Describe Variable (m-X) 
Displays the documentation and current value for a Zmacs variable. It reads 
the variable name from the minibuffer, using completion. 


Describe Variable At Point (c-sh-) 
Displays information, in the echo area, about ihe current Lisp variable. The 
information includes whether the variable is declared special, whether it has a 
value, what file defines it, and whether it has documentation put on by defvar 
or defconst. When nothing is available, it checks for lookalike symbols in 
other packages. 


(disassemble function) (see also mexp) 

Displays the macro-instructions for the function. It does not work for 
functions that are not compiled or that are implemented in microcode, like 
cons or car. (See How to Read Assembly Language in the Lisp Machine 
Manual.) 

(disassemble ’plus) 


Use this function for things like finding clues about whether a macro is being 
expanded correctly. : 


(documentation function) 
Returns the documentation string for a function or variable. It returns nil 
when no documentation has been provided. (Note: as of Release 4.0, very few 
functions have associated documentation.) 
(documentation *zwei:com-quick-arglist) 


Edit Buffers (m-X) (see also List Buffers) 
Displays a list of all buffers, allowing you to save or delete buffers and to 
select a new buffer. A set of single character subcommands lets you specify 
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- various operations for the buffers. For example, you can mark buffers to be 
deleted, saved, or not modified. Use HELP to see further explanation. The 
buffer is read-only; you can move around in it by searching and with 
commands like c-N or c-P. 


Edit Callers (m-X) (see also List Callers, Multiple Edit Callers) 

Prepares for editing all functions that call the specified one. It reads a function 
name via the mouse or from the minibuffer with completion. By default, it 
searches the current package. You can control the package being searched by 
giving the function an argument. With c-U, it searches all packages; with c-U 
e-U, it prompts for a package name. It selects the first caller; use c—-. (Next 
Possibility) to move to a subsequent definition. It takes about 5 minutes to 
search all packages. 


Edit Changed Definitions (m-X) (see also List Changed Definitions) 
Determines which definitions in any Lisp mode buffer have changed and selects 
the first one. It makes an internal list of all the definitions that have changed 
in the current session and selects the first one on the list. Use c-. (Next 
Possibility) to move to a subsequent definition. Use a numeric argument to 
control the starting point for determining what has changed: 
1 ‘~For each buffer, since the file was last read (the default). 
2 ~+=For each buffer, since it was last saved. 
3. ‘For each definition in each buffer, since the definition was last compiled. 


Edit Changed Definitions Of Buffer (m-X) (see also List Changed Definitions Of Buffer) 
Determines which definitions in the buffer have changed and selects the first 
one. It makes an internal list of all the definitions that have changed since the 
buffer was read in and selects the first one on the list. Use c-. (Next 
Possibility) to move to subsequent definitions. Use a numeric argument to 
control the starting point for determining what has changed: 

1 Since the file was last read (the default). 
2 Since the buffer was last saved. 
3 Since the definition was last compiled, for each definition in the buffer. 


Edit Combined Methods (m-X) (see also List Combined Methods) 
Prepares to edit the methods for a specified message to a specified flavor. It 
prompts first for a message name, then for a flavor name. It selects the first 
combined method component. Use c-. (Next Possibility) to move to a 
subsequent definition. The definitions appear in the order that they would be 
called when the message was sent. Error messages appear when the flavor does 
not handle the message and when the flavor requested is not a composed, 
instantiated flavor. 


Edit Compiler Warnings (m-X) (see also Compiler Warnings) 
Prepares to edit all functions whose compilation caused a warning message. It 
queries, for each of the files mentioned in the database, whether you want to 
edit the warnings for the functions in that file. It splits the screen, putting the 
warning message in the top window. The bottom window displays the source 
code whose compilation caused the message. Use c-. (Next Possibility) to 
move to a subsequent warning and source function. After the last warning, it 
returns the screen to its previous configuration. 


Edit Definition (m-. ) 
Prepares to edit the definition of a function, variable, flavor, or anything else 
defined with a "defsomething" special form. It prompts for a definition name 
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from the minibuffer. Name completion is available for definitions in files that 
have already been loaded into buffers. You can select a name by clicking the 
mouse over a definition name in the current buffer. It selects the buffer 
containing the definition for that name, first reading in the file if necessary. 
With a numeric argument, it selects the next definition that satisfies the most 
recent name given. It tells you in the echo area when it finds more than one 
definition for a name. 


Edit File Warnings (m-%) 
Prepares to edit any functions in a specified file for which warnings exist. It 
prompts for a file name, which can be either a source file or a compiled file. It 
splits the screen, putting a warning message from the warnings database in the 
top window. The bottom window displays the source code whose compilation 
caused the message. If the database does not contain any warnings for this file, 
it prompts for the name of a file containing the warnings. Use c-. (Next 
Possibility) to move to a subsequent warning and source function. After the 
last warning, it returns the screen to its previous configuration. 


Edit Methods (m-) (see also List Methods) 
Prepares to edit all the methods on any flavor for a particular message. It 
prompts for a message name. It finds all the flavors with handlers for the 
message, makes an internal list of the method names, and selects the definition 
for the first one. Use c-. (Next Possibility) to move to subsequent definitions. 


Edit Zmacs Command (m-%) 
Finds the source for the function installed on a key. You can press any key 
combination or enter an extended command name. Use a numeric argument to 
edit the function that implements a prefix command (like m-X or c-%). 


Evaluate And Exit (c-m-2) 
Evaluates the buffer and returns from top level. It selects the window from 
which the last (ed) function or the last debugger c-E command was executed. 


Evaluate And Replace Into Buffer (m-%) 
Evaluates the Lisp object following point in the buffer and replaces it with its 
result. 


Evaluate Buffer (m-%) 
Evaluates the entire buffer. With a numeric argument, it evaluates from point 
to the end of the buffer. 


Evaluate Changed Definitions (m-x) 
Evaluates any definitions that have changed in any buffers. With a numeric 
argument, it prompts individually about whether to evaluate particular changed 
definitions. 

Evaluate Changed Definitions Of Buffer (n-sh-E, m-%) 
Evaluates any definitions in the current buffer that have been changed. With a 
numeric argument, it prompts individually about whether to evaluate particular 
changed definitions. 


Bae Into Buffer (m-%) 
Evaluates a form read from the minibuffer and inserts the result into the 
buffer. You enter a Lisp form in the minibuffer, which is evaluated when you 
press END. The result of evaluating the form appears in the buffer before 
point. With a numeric argument, it also inserts any et that occurs during 
the evaluation into the buffer. 
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Evaluate Minibuffer (m-ALTMODE) 
Evaluates forms from the minibuffer. You enter Lisp forms in the minibuffer, 
which are evaluated when you press END. The value of the form itself appears 
in the echo area. If the form displays any output, that appears as a typeout 
window. 


Evaluate Region (c-sh-E, m-%) 
Evaluates the region. When no region has been defined, it evaluates the 
current definition. It shows the results in the echo area. 


Evaluate Region Hack (m-%) 
Evaluates the region, ensuring that any variables appearing in a defvar have 
their values set. When no region has been defined, it evaluates the current 
definition. It shows the results in the echo area. 


Evaluate Region Verbose (c-m-sh-E) 
Evaluates the region. When no region has been defined, it evaluates the 
current definition. It shows the results in a typeout window. 


(flavor-allowed-init-keywords flavor-name) (In si:) 
Returns a list containing the init keywords and inittable instance variables 
allowed for a particular flavor. 
(si:flavor-allowed-init-keywords *tv:basic-menu) 


Function Apropos (m-%) 
Displays all the Lisp functions whose print names contain a particular substring. 
It reads the substring from the minibuffer. By default, it searches the current 
package. You can control the package being searched by giving the function an 
argument. With c-U, it searches all packages; with c-U c-U, it prompts for a 
package name. 


(inspect object) (see also describe) 
Creates or selects an Inspector window and displays available information about 
an object. inspect and describe provide similar information, except that 
inspect is an interactive facility for further exploring a data structure. 
(inspect tv:selected-window) 
(inspect (tv:window-under -mouse) ) 


List Buffers (c-X c-B) (see also Edit Buffers) 
Prints a list of all the buffers and their associated files. The lines in the list 
are mouse-sensitive, offering a menu of operations on the buffers. Clicking left 
on a line selects the buffer. For buffers with associated files, the version 
number of the file appears. For buffers without associated files, the size of the 
buffer in lines appears. For Dired buffers, the pathname used for creating the 
buffer appears as the version. The list of buffers appears sorted in order of last 
access, with the currently selected one at the top. You can inhibit sorting by 
setting zwei:*sort-zmacs-buffer-list* to nil. 


List Callers (m-X) (see also Edit Callers, Multiple List Callers) 
Lists all functions that call the specified function. It reads a function name via 
the mouse or from the minibuffer with completion. By default, it searches the 
current package. You can control the package being searched by giving the 
function an argument. With c-U, it searches all packages; with c-U c-U, it 
prompts for a package name. The names are mouse-sensitive. Use c-. (Next 
Possibility) to start editing the definitions in the list. It takes about 5 minutes 
to search all packages. © 
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List Changed Definitions (m-X) (see also Edit Changed Definitions) 
Displays a list of any definitions that have been edited in any buffer. Use c-. 
(Next Possibility) to start editing the definitions in the list. Use a numeric 
argument to control the starting point for determining what has changed: 
1 ‘*For each buffer, since the file was last read (the default). 
2 ~=For each buffer, since it was last saved. 
3 For each definition in each buffer, since the definition was last compiled. 


List Changed Definitions Of Buffer (m-X) (see also Edit Changed Definitions Of Buffer) 

Displays the names of definitions in the buffer that have changed. It makes an 
internal list of the definitions changed since the buffer was read in and offers 
to let you edit them. Use c-. (Next Possibility) to move to subsequent 
definitions. Use a numeric argument to control the starting point for 
determining what has changed: 

1 Since the file was last read (the default). 

2 Since the buffer was last saved. 

3 Since the definition was last compiled, for each definition in the buffer. 


List Combined Methods (m-%) (see also Edit Combined Methods) 
Lists the methods for a specified message to a specified flavor. It prompts first 
for a message name, then for a flavor name. It lists the names in a typeout 
window. Error messages appear when the flavor does not handle the message 
and when the flavor requested is not a composed, instantiated flavor. Use c-. 
(Next Possibility) to start editing the definitions in the list. 


List Commands (m-%) 
Lists names and one-line summaries for all extended commands available in the 


current context. It displays the names in a typeout window. The list is not 
sorted. 


List Definitions (m-X) 
Displays the definitions from a specified buffer. It reads the buffer name from 
the minibuffer, using the current buffer as the default. It displays the list as a 
typeout window. The individual definition names are mouse-sensitive. 


List Matching Lines (m—-X) 
Displays all the lines following point in the current buffer that contain a given 
string. It prompts for the string in the minibuffer. With a numeric argument, 
it shows only the first 2 occurrences of the string following point. It does not 
accept a numeric argument. The lines are mouse-sensitive. 


List Matching Symbols (m-x) 
Lists the symbols that satisfy a predicate. It prompts for a predicate lambda 
expression of one argument. The predicate gets compiled, for speed. The 
predicate must return something other than nil for the symbol to be included 
in the list. For example 
you pressed: m-X LMS 
minibuffer contains: °(LAMBDA (SYMBOL) ) 

revised minibuffer: °(LAMBDA (SYMBOL) (string-search "foo" symbol)) 
By default, it searches the current package. You can control the package being 
searched by giving the function an argument. With c-U, it searches all 
packages; with c-U c-U, it prompts for a package name. It selects the first one; 
use c-. (Next Possibility) to move to a subsequent definition. 


List Methods (m-X) (see also Edit Methods) 


November 1982 15 Symbolics, Inc. 


Symbolics, Inc. Program Development Help Facilities 


Lists all the function specs for all methods on any flavor that handle a 
particular message. It prompts for the message name. It finds all the flavors 
with methods for the message and displays the information in a typeout 
window. The function specs are mouse-sensitive. 


List Registers (m-X) 
Displays names and contents of all defined registers. Use Apropos to see 
commands for manipulating registers. 


List Some Word Abbrevs (m-%) | 
Lists the abbreviations or expansions that contain the given string. Use 
Apropos to see the other abbreviation commands. 


List Tag Tables (m-%) 
Lists the names of all the tag tables currently available. Use Apropos to see 
other commands using tags. 


List Variables (m-X) 

Lists all Zmacs variable names and their values. With a numeric argument, it 
also displays the documentation line for the variable. Zmacs variables are those 
that have been provided for customizing the editor. Their names differ from 
their internal Lisp names: 


Zmacs variable name: Fill Column 
Internal Lisp name: zwei:*fill-column* 


List Word Abbrevs (m-%) 
Lists all current abbreviations and their expansions. 


(load-compiler-warnings file flush-flag) (In compiler:) 
Loads a file containing compiler warning messages into the warnings database. 
The file should contain the printed representation of compiler warnings (as 
saved by print-compiler-warnings). It uses flush-flag to determine whether 
to replace any of the warnings already in the database. When the flag is not 
nil, it deletes any warnings associated with a source file before loading any new 
warnings for that file. Otherwise, it merges warnings from the file with those 
_ already in the warnings database. The default is t. 


Load Compiler Warnings (m—-%) 
Loads a file containing compiler warning messages into the warnings database. 
It prompts for the name of a file that contains the printed representation of 
compiler warnings. It always replaces any warnings already in the database. 


Long Documentation (m-sh-D) (see also Brief Documentation) 
Displays the summary documentation for the specified Lisp function. It 
prompts for a function name, which you can either type in or select with the 
mouse. The default is the current function. 


m—. See Edit Definition. 

m-ALTMODE = —- See Evaluate MiniBuffer. 

m—-sh-C See Compile Changed Definitions Of Buffer. 
m-sh-D See Long Documentation. 

m-sh-E See Evaluate Changed Definitions Of Buffer. 


Macro Expand Expression (c-sh-M, m-X) 
Displays the macro expansion of the next Lisp expression in the buffer. It 
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reads the Lisp expression following point and expands all macros within it at all 
levels, displaying the result on the typeout window. With a numeric argument, 
it pretty-prints the result back into the buffer, immediately following the 
expression. 


(mexp) (see also disassemble) 
Displays the expansion of a macro. It prompts for a macro invocation to 
expand and then displays its expansion without evaluating it. It continues 
prompting until you enter something that is not a cons (for example, () stops 
it.) 

Multiple Edit Callers (m-) (see also Edit Callers) 
Prepares for editing all functions that call the specified ones. It reads a 
function name from the minibuffer, with completion. It then keeps asking for 
another function name until you end it with just RETURN. By default, it 
searches the current package. You can control the package being searched by 
giving the function an argument. With c-U, it searches all packages; with c-U 
c-U, it prompts for a package name. It selects the first caller; use c-. (Next 
Possibility) to move to a subsequent definition. 


Multiple List Callers (m-X) (see also List Callers) 
Lists all the functions that call the specified functions. It reads a function 
name from the minibuffer, with completion. It continues prompting for a 
function name until you end it with just RETURN. By default, it searches the 
current package. You can control the package being searched by giving the 
function an argument. With c-U, it searches all packages; with c-U c-U, it 
prompts for a package name. Use c-. (Next Possibility) to start editing the 
definitions in the list. 


Print Modifications (m-X) 
Displays the lines in the current buffer that have changed since the file was 
first read into a buffer. With a numeric argument, it displays the lines that 
have changed since the last save. To provide context, it shows the first line of 
each section that contains a change, whether or not that line has changed. The 
lines are mouse-sensitive, allowing you to move to the location of a change. 


Quick Arglist (c-sh-A) (see also arglist) 
Displays the argument list for the current function. With a numeric argument, 
it reads the function name via the mouse or from the minibuffer. When the 
original function uses a values declaration, Quick Arglist returns the names for 
the values returned by the function. 


Quit (c-zZ) Returns from top level. It selects the window from which the last (ed) 
function or the last debugger c-E command was executed. 


Select System as Tag Table (m-%) 
Creates a tags table for all the files in a system. It uses the file names as they 
appear in the defsystem function for that system. 


Tags Search (m-) Searches all files in a tags table for a specified string. It reads the string from 
the minibuffer and then prompts for a tags table name. 


Trace (m-X) (see also untrace) 
Toggles tracing for a function. It uses the same interface for specifying options 
as the Trace program in the system menu. See Lisp Machine Manual, p. 457. 


(trace specs) (see also untrace) 
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Turns on tracing for a function. With no arguments, it returns a list of all 
things currently being traced. With no additional options, tracing displays the 
name and arguments for a function each time it is called and its name and 
value(s) each time it returns. Complex options are available for entering 
breakpoints or executing code conditionally during tracing. See Lisp Machine 
- Manual, p. 457, and the Trace command in Zmacs. 
(trace foo bar) 
(trace #°(:method command-found :push) ) 


Tracing very common functions (like format) or functions used by trace itself 
or by the scheduler (like time:get-time) can crash the machine. 


(untrace specs) Turns off tracing for a function that is being traced. With no argument, it 
turns off tracing for all functions currently being traced. 


(variable-boundp variable) 
Returns nil or t indicating whether or not the variable is bound. 
(variable-boundp tv:current-window) 


(what-files-call symbol package) 
Displays the names of files that contain uses of symbol as a function, variable, 
or constant. It searches all the function cells of all the symbols in package. By 
default, it searches the global package and its descendants. It returns a list of 
the pathnames of the files containing the callers. 


Where Is Symbol (m-) 
Displays the names of packages that contain symbols with the specified name. 


(where-is string package) 


Displays the names of all packages that contain a symbol whose print name is 

string. It ignores the case of string. By default, it looks in the global package 

and its descendants. where-is returns a list of the symbols that it finds. 
(where-is "foobar") 


(who-calls symbol package inferiors superiors) 
Displays a line of information about uses of the symbol as a function, variable, 
or constant. It searches all the function cells of all the symbols in package. By 
default, it searches the global package and its descendants. It returns a list of 


the names of the callers. 
(who-calls *time:get-time ’hacks) 
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Notes 


November 1982 19 Symbolics, Inc. 


symbolics ™ 


Program Development Help Facilities 
#990093 


Design: Schafer/LaCasse 
Typesetting: Cover — Litho Composition Co. 
Printing: Henry Sawyer Co. 
Sa 5 EES ek AS a a IN a A NN TN SLE I WGN EI TEE hE SR CSET Ta eR a 


